What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
flatpak-builder builds Flatpak applications from a JSON or YAML manifest: the manifest describes the app, its runtime and SDK, source code, build steps, and required sandbox permissions. The usual workflow is to prepare the manifest, build and test the app, then export it to a repository for installation and distribution.
What flatpak-builder does
Flatpak’s documentation calls flatpak-builder its primary application-building tool. It reads a manifest, downloads and verifies module sources, initializes a build directory, builds and installs modules in the SDK environment, cleans the output, applies the app’s finishing configuration, and can export the result to a repository. Dependencies can be built alongside the application. See the building introduction and first-build tutorial.
As an Amazon Associate I earn from qualifying purchases.
flatpak-builder <build-dir> <manifest>The build directory is an intermediate workspace, not usually the artifact you distribute. It is useful for diagnosing build problems.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Choose a runtime and SDK, then write the manifest
A manifest is the build recipe. It typically specifies an application ID, runtime, runtime-version, sdk, and command, followed by module definitions containing source locations and build instructions. The runtime provides the app’s base environment; its matching SDK supplies compilers, headers, and other development tools. Consult the manifest reference for the available fields and source types.
#1 Best Overall
Select a runtime branch supported by the repository where you plan to publish, and ensure the SDK corresponds to that runtime. The official tutorial uses Freedesktop 25.08 as an example; that is an example branch, not a permanent recommendation.
Flatpak recommends naming the manifest after the application ID, for example org.gnome.Dictionary.yml. Exported desktop files, icons, and app metadata also need application-ID-based names. If upstream filenames differ, manifest rename options are available, though renaming files in the source tree is described as more reliable.
Rank #2
Build, install, and launch the app
The official tutorial demonstrates this command for its org.flatpak.Hello example:
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Repair Windows errors before they cause bigger problems3Fix the driver behind crashes, sound loss and screen glitchesflatpak-builder --force-clean --user
--install-deps-from=flathub --repo=repo --install
builddir org.flatpak.Hello.ymlThis builds the manifest’s modules, installs the generated application for the current user, and exports it to the local repo repository. Run the example with:
flatpak run org.flatpak.HelloFor a real application, substitute your own app ID and manifest, choose the appropriate runtime branch and modules, and set permissions that match the app. The flags above are the tutorial’s example workflow, not mandatory settings for every project. The official first-build guide walks through that example.
Declare only the sandbox access the app needs
Flatpak applications have limited host access by default. The manifest’s finish-args declares access needed at runtime. Official examples include display access, graphics-device access, network access, and access to a selected documents directory. Add permissions only when required for a specific app function, and explain the reason in project documentation. The manifest documentation describes permission options.
Tests can have separate permissions from the installed application. The developer documentation describes run-tests, test-rule, test-commands, and test-args; test arguments can, for example, enable X11 or network access during tests without changing the app’s normal permissions. See Flatpak developer documentation.
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 matchExport and distribute the build
To export a build into a repository, use the repository option with the build directory and manifest:
flatpak-builder --repo=repo builddir org.example.App.ymlThis can add a new version of an application already in the repository. You can also use --install to install the generated app locally as part of the build workflow. Flatpak’s guidance recommends signing repository commits with a GPG signature. See the flatpak-builder documentation.
| Distribution method | Updates | Dependencies and AppStream data | Best fit |
|---|---|---|---|
| Repository | Supports updates | Repository-based distribution; consult repository setup guidance for publication details | Ongoing online distribution |
| Single-file bundle | Not identified as the update-capable route in the cited bundle guidance | Does not include dependencies or AppStream data | A limited transfer case, not a complete self-contained package |
flatpak create-usb |
Not stated in the cited offline-distribution guidance | Preferred by the documentation for offline distribution | Offline transfer |
The documentation prefers repositories for update-capable distribution. A bundle can be created with flatpak build-bundle, but because it omits dependencies and AppStream data, it should not be presented as a fully self-contained offline package. For offline sharing, the documentation points to flatpak create-usb. Details are in the single-file bundle guide.
Quick Recap
What to check when a build does not work
- Runtime or SDK unavailable: Check that the manifest’s runtime branch is supported by the target repository and that the corresponding SDK is available.
- Source download or verification fails: Review the module’s source definition and the source host’s availability; module sources are downloaded and verified before builds begin.
- Build succeeds but the app does not launch: Verify the manifest’s
commandand application-ID-based desktop and metadata filenames. - A feature cannot access a device, display, network, or documents: Check whether the app needs a narrowly scoped
finish-argspermission. - Tests fail but the app’s normal sandbox is intentionally restricted: Configure test-specific permissions or arguments rather than broadening runtime access just to make tests pass.
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.
