A Flatpak manifest is the build recipe and dependency declaration for an app; it is not the runtime itself. The runtime provides the app’s basic execution environment, the matching SDK provides tools to build it, and an extension adds optional content when it matches an extension point declared by the app or runtime.
What a Flatpak manifest does
flatpak-builder reads a manifest written in JSON or YAML. The manifest describes the application and how to build it, including its ID, runtime, runtime branch, SDK, launch command, and build modules. The runtime and runtime-version fields identify the execution environment the app depends on, so Flatpak can arrange for that runtime to be installed on a user’s system.
A manifest can contain multiple modules. Each module can identify source code and build instructions; commonly, the application’s own code is the last module. flatpak-builder downloads and verifies sources, builds and installs the modules, applies sandbox permissions, and exports the result to a repository. See the Flatpak manifest documentation and build introduction.
Runtime versus SDK
The runtime is the environment an app uses when it runs, including its basic dependencies. The SDK is the corresponding development environment used to build the app; it includes tools and resources such as compilers, headers, and packaging tools. Flatpak’s first-build tutorial describes the matching SDK as a superset of the runtime.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware match#1 Best Overall
| Component | Purpose | Where it is identified |
|---|---|---|
| Runtime | Provides the app’s basic execution environment and dependencies. | runtime and runtime-version in the manifest |
| SDK | Provides the development tools and resources used to build the app. | sdk in the manifest |
| Manifest | Describes the app, its dependencies, launch command, and build recipe. | JSON or YAML file read by flatpak-builder |
The runtime and SDK should correspond: the runtime is for execution, while the matching SDK is for development. The manifest connects these choices to the build and to the dependency users need to run the finished app.
Choosing a runtime family and branch
Flatpak documentation describes Freedesktop, GNOME, and KDE as the three main runtime families hosted on Flathub. Freedesktop is a general-purpose base; GNOME provides GNOME platform libraries and components; KDE provides Qt and KDE Frameworks. Each has a corresponding SDK and commonly supplied Docs, Debug, and Locale extensions. Choose based on the frameworks and libraries the app needs, then check that the chosen branch is compatible with those requirements. The available runtimes guide describes the families and their branches.
The same guide describes lifecycle patterns, not a guarantee that a particular branch is still current: Freedesktop branches have a two-year support period, with a new major version published each August; GNOME runtime major versions follow GNOME releases and are usually supported for a year; KDE branch patterns relate to Freedesktop releases and Qt versions. Verify current branch availability and end-of-life status with the runtime project before selecting a branch, since those details change.
How extension points and extensions work
An extension point is metadata declared by an app or runtime. It defines a location and conditions under which compatible optional extension runtimes can be mounted inside the sandbox. Extensions can supply items such as translations, SDK debug information, or additional functionality. The extension point is the declared interface; an extension is the payload that may be mounted there. Flatpak’s extension documentation explains the metadata and matching behavior.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minuteRank #3
Check the declared interface
Find the extension point in the app’s or runtime’s manifest. Its metadata—not a naming convention inferred on its own—sets the requirements an extension must meet. For example, the documentation uses the point ID org.flatpak.app.plugin.
Match the extension ID and branch
The extension ID must begin with the extension point ID; an example matching ID is org.flatpak.app.plugin.foo. The extension’s branch must equal the extension point’s declared version. A similar-looking ID or a different branch does not satisfy those matching rules.
Match the parent runtime and conditions
In the extension manifest, runtime should identify the parent module where the point is defined, and runtime-version should be the runtime version used by the application. The extension is mounted only when the matching branch is installed and the extension point’s conditions are met. When several extensions are mounted, they are arranged in alphabetical path order.
Account for automatically handled extensions
Some runtime-provided extensions are installed automatically. The .Locale and .Debug extensions generated by flatpak-builder also do not need to be redundantly listed in the app manifest. Locale extensions are generally installed only in part, according to the system’s configured languages. The dependencies guide covers runtime and extension dependencies.
Best Value
Adding a custom extension point to a manifest
Define an extension point in the app or runtime manifest, then make the extension conform to that declared interface. For a custom extension, verify these fields and conditions against the point:
- Point ID: Identify the extension point declared by the parent. This determines the required ID prefix.
- Extension ID: Start the extension ID with the point ID; for example, a point named
org.flatpak.app.plugincan matchorg.flatpak.app.plugin.foo. - Branch: Set the extension branch to the point’s declared
version. - Parent runtime: Set the extension manifest’s
runtimeto the parent module where the point is defined, and setruntime-versionto the application’s runtime version. - Installation and conditions: Ensure the matching branch is installed and the extension point’s conditions are satisfied; otherwise, the extension will not be mounted.
Do not assume that an extension is available just because its ID looks related. The point’s actual metadata controls compatibility and mounting.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
