FLATPAK-BUILDER(1)

📦

version 1.4.12 · 17 versions

1.4.12 · arch rolling, ubuntu stonking (latest)
1.4.4 · opensuse-leap 16.0
1.4.4 · nixos 26.05
1.2.3 · centos-stream 9
1.4.7 · centos-stream 10
1.4.10 · nixpkgs unstable
1.4.11 · alpine 3.24
1.4.6 · ubuntu questing
1.4.12 · fedora 43
1.4.4 · fedora 43
1.2.2 · ubuntu jammy
1.4.12 · fedora 44
1.4.7 · fedora 44
1.2.3 · debian bookworm
1.4.2 · ubuntu noble
1.4.8 · ubuntu resolute
1.4.4 · debian trixie

🦋 NAME 🦋

okay bestie, meet flatpak-builder — she's here to help you build applications and all their adorable little dependencies. 💖

✨ SYNOPSIS ✨

flatpak-builder [OPTION...] DIRECTORY MANIFEST

flatpak-builder --run [OPTION...] DIRECTORY MANIFEST COMMAND

flatpak-builder --show-deps [OPTION...] MANIFEST

flatpak-builder --show-manifest [OPTION...] MANIFEST

🌸 DESCRIPTION 🌸

flatpak-builder is basically a glow-up wrapper around the flatpak build command — it automates the whole "build my app + everything it depends on" situation. It's one option you can use to build applications. Just one! There are others! But this one is ours. 💅

The whole goal here? Push as much knowledge about how to build modules back onto the individual upstream projects. The way it does that is by assuming the modules follow the Build API spelled out at https://github.com/cgwalters/build-api. Which essentially means it follows the classic ./configure && make && make install scheme, with an optional autogen script. And if upstream is not following the API? No worries bestie, you can make it behave by adding patches and extra files. iconic.

Here's the pipeline — one invocation of flatpak-builder goes through these stages, and each one is specified in detail in json format in MANIFEST:

Download all sources
Initialize the application directory with flatpak build-init
Build and install each module with flatpak build
Clean up the final build tree by removing unwanted files and e.g. stripping binaries
Finish the application directory with flatpak build-finish

So after all that, you end up with a build of the app in DIRECTORY 🎀 — which you can export to a repository using the flatpak build-export command. OR, if you pass the --repo option, flatpak-builder will do that export for you at the end of the build. So generous of her. And when she does the export, she also stores the manifest used for the build in /app/manifest.json. That manifest is 'resolved' — meaning git branch names get swapped out for the actual commit IDs that were used in the build. no cap, it keeps receipts. 🧾✨

At every one of those steps, flatpak caches the result. So if you build the same file again, it starts at the first step where something actually changed. Like — the first version-controlled source that got new commits, or the first module where changes to the MANIFEST file made the build environment shift. This is why flatpak-builder is so efficient for incremental builds. main character energy fr. 👑

💜 Quick PSA: when you're building a flatpak that's going to be published to the internet, you should specify --collection-id=COLLECTION-ID as a globally unique reverse DNS value, to identify the collection of flatpaks this one will be added to. Setting a globally unique collection ID is what lets the apps in the repository be shared over peer-to-peer systems without needing any further configuration. slay.

🎀 MANIFEST 🎀

The manifest file is a json or yaml file, and its format is described in detail in its own manual page. (Go read that one too, bestie, this is a two-manpage kind of situation.) 🫶

💅 OPTIONS 💅

Here are all the options she understands:

-h, --help — Shows you the help options, then dips out. exit. bye. ✌️
-v, --verbose — Prints debug info while the command is processing, so you can see exactly what's going on in there. 🔍
--version — Prints version info and exits.
--arch=ARCH — Tell her which machine architecture to build for. If you don't specify one, the host architecture gets detected automatically. Heads up: only host-compatible architectures can be specified. That's the rule, periodt.
--default-branch=BRANCH — Sets the default branch to BRANCH. This kicks in when the manifest doesn't specify a branch itself. The default is master.
--disable-cache — Don't even look at the existing cache from a previous build. Just always rebuild modules. fresh start energy. 🦋
--disable-rofiles-fuse — Disables the use of rofiles-fuse, which is what optimizes cache use via hardlink checkouts. no fuse, no hardlink checkout magic.
--disable-download — Don't download any sources. ⚠️ This only works if some version of all the sources is already downloaded. It's super useful when you want to guarantee that no network i/o happens at all. BUT — the build will fail if some source isn't locally available. so, like, know that going in.
--disable-updates — Downloads missing sources, but does not update local mirrors of version control repos. Great for rebuilding things without updating your git, bzr or svn repositories from the remote. lowkey the move for reproducibility.
--disable-tests — Don't run any of the tests. 🙈
--run — Runs a command inside a sandbox based on the build dir. This starts flatpak build with some extra arguments, so you get the same environment as the build and the same permissions the final app will have (except filesystem permissions, obviously). The command to run has to be the last argument passed to flatpak-builder, after the directory and the manifest.

💀 Only these can be combined with this option: --arch=ARCH, --ccache, --verbose and --state-dirPATH (since 1.4.8). that's it, that's the list.

--build-shell=MODULENAME — Extracts and prepares the sources for the named module, then drops you into a shell in a sandbox identical to the one flatpak-builder would use for building that module. Perfect for debugging a module. debugging arc era. 🐛
--show-deps — Lists all the (local) files that the manifest depends on.

Only --verbose can be combined with this option.

--show-manifest — Loads the manifest, including any included files, and prints it out in a canonical json format. This is chef's kiss for tools that want to handle manifest files, because it means they don't have to support both yaml and json — plus all the non-standard json handling that's supported (for example comments and multiline strings). 👑

Only --verbose can be combined with this option.

--download-only — Exits successfully right after downloading the required sources. that's the whole job. ✨
--bundle-sources — Creates an additional runtime holding the source code for this module. It'll be named app-id.Sources — for example org.gnome.Maps.Sources.
--build-only — Skips the cleanup and finish stages. Useful if you want to build more things into the app. 🏗️
--finish-only — Only does the cleanup, finish and export stages, picking up exactly where a --build-only command left off. seamless.
--export-only — Only does the export stages, picking up the build result from a previous build. This is how you split the build and the export/signature into two separate calls, by leaving out --repo in the first one.
--require-changes — Does nothing, and leaves a non-existent DIRECTORY if nothing has changed since the last cached build. If you don't specify this, the latest version from the cache gets put into DIRECTORY instead.
--state-dir=PATH — Use this directory for storing state (downloads, build dirs, build cache, etc) instead of .flatpak-builder. It can be an absolute or relative path, but it must be on the same filesystem as the target DIRECTORY you specified. important!!
--keep-build-dirs — Doesn't remove the sources and build after having built and installed each module. This also creates a symlink to the build directory with a stable name ("build-modulename"). 💖
--delete-build-dirs — Always removes the sources and build after each module is built, even if the build failed. The default behaviour is to keep failed build directories but remove successful ones. This option is useful in e.g. automatic build systems.
--ccache — Enables use of ccache in the build (needs ccache in the sdk, so make sure it's actually there bestie). The default ccache folder can be overridden by setting the environment variable CCACHE_DIR.
--stop-at=MODULENAME — Stops at the specified module, ignoring it and all the following ones in both the "download" and "build" phases. Great for debugging and development. For instance, you can build all the dependencies but stop at the main application, so you can then do a build from a pre-existing checkout. Implies --build-only.
--repo=DIR — After the build finishes, runs flatpak build-export to export the result into the repository DIR. If DIR already exists, it must be an OSTree repository; otherwise a new one gets created. ✨
-s, --subject=SUBJECT — A one-line subject for the commit message. Used when exporting the build results.
-b, --body=BODY — The full description for the commit message. Used when exporting the build results.
--collection-id=COLLECTION-ID — Sets the collection ID of the repository. Setting a globally unique collection ID lets the apps in the repository be shared over peer-to-peer systems without needing further configuration. ⚠️ But if you're building into an existing repository, the collection ID must match the existing configured collection ID for that repository. no mismatches allowed.
--token-type=VAL — Sets the type of token needed to install this commit. Setting this to a value greater than 0 implies that authentication will be needed to install the flatpak. A token-type property set in the manifest takes precedence over this option. Used when exporting the build results.
--gpg-sign=KEYID — Signs the commit with this GPG key. Used when exporting the build results. This option can be used multiple times. 🔐
--gpg-homedir=PATH — The GPG Homedir to use when looking for keyrings. Used when exporting the build results.
--jobs=JOBS — Limits the number of parallel jobs during the build. The default is the number of CPUs on the machine. multitasking queen. 👑
--force-clean — Erases the previous contents of DIRECTORY if it isn't empty. Since 1.4.6, deletion will be refused if DIRECTORY is the current working directory, the state directory, or any of their parent directories. she protects herself. 🛡️
--sandbox — Disables the possibility of specifying build-args that get passed to flatpak build. This means the build process can't break out of its sandbox, which is very much the vibe when you're building less trusted software.
--allow-missing-runtimes — Don't immediately fail if the sdk or platform runtimes aren't installed on this system. Note: attempting to build any manifest modules will still fail if the sdk is missing — but this can be useful for apps that install files without a sandbox build.
--rebuild-on-sdk-change — Records the exact version of the sdk in the cache, and rebuilds everything if it changes. Super useful if you're building against an API-unstable runtime, like a nightly build. 🌙
--skip-if-unchanged — If the json is unchanged since the last build of this filename, then do nothing and return exit code 42. iconic number, honestly. 🌈
--mirror-screenshots-url=URL — okay so this one takes all the media chillin in the appstream and mirrors it, then rewrites the media URLs in the appstream xml so they point at URL instead. Where do the files land? Depends on your version, bestie: for versions earlier than 1.3.4 they go in the screenshots subdirectory inside the app directory, and for newer versions it's the files/share/app-info/media subdirectory. And since version 1.4.5 it also creates a screenshot ref in the exported OSTree repo for each architecture that has mirrored media. multitasking queen 💅
--extra-sources=SOURCE-DIR — when flatpak-builder is downloading sources (archives, files, git, bzr, svn) it'll peek in this directory for pre-existing copies and use those instead of downloading. 🎀 The directory has to match the state directory structure exactly, no improvising:
- Files and archives must be inside the folder: downloads/<sha256>/
- Sources of type git, bzr and svn must be inside the folder: <type>/<converted-uri>/

Now the <converted-uri> — it's built from path or url (for git) and from url (for bzr and svn). The conversion is iconic: :// becomes a single underscore, and every other / gets replaced by an underscore. So for example https://github.com/user/repo.git becomes https_github.com_user_repo.git. And for svn sources, if a revision is present the folder name is svn/<converted-uri>__r<revision>/. For git sources, it needs to be a mirrored clone, no cap. ✨

--extra-sources-url=URL — when downloading sources (archives, files, git, bzr, svn), check this url for mirrored downloads before downloading from the original url. polite behavior honestly 🫶
--from-git=GIT — look for the manifest inside the given git repository. If you pass this, then MANIFEST is interpreted as a relative path inside that repo. 📁
--from-git-branch=BRANCH — the branch to use with --from-git. they come as a set, iykyk 💖
--no-shallow-clone — don't use shallow clones when mirroring git repos. that's it, that's the tweet 🦋
--override-source-date-epoch — set this timestamp as SOURCE_DATE_EPOCH to perform the build, instead of the last modification time of the manifest. available since 1.3.1. ⏰
--compose-url-policy=POLICY — sets the AppStream compose URL policy. accepted values are partial and full. heads up: full requires AppStream version >= 0.16.3. defaults to partial if you don't specify. and listen — this policy only takes effect when used in conjunction with --mirror-screenshots-url=URL; otherwise the Appstream catalogue will preserve the source media URLs. so it's giving main character only when it's got its partner 🔥
--compose-image-format=FORMAT — sets the AppStream compose image format used for generated icons and screenshots. accepted values are png and jxl. jxl requires AppStream version >= 1.2.0. defaults to png if unspecified. 🌸
--add-tag=TAG — add this tag to the tags list of the manifest before building. 🏷️
--remove-tag=TAG — remove this tag to the tags list of the manifest before building. and the remove happens before processing the --add-tag option, so if both are specified, then --app-tag wins. yes that's exactly what it says, bestie 💀
--install-deps-from=REMOTE — install/update build required dependencies from the specified remote. 💅
--install-deps-only — stop after downloading dependencies. that's the whole job, clock out ✌️
--install — when the build is finished, install the result locally. 🎀
--user — install the dependencies in a per-user installation.
--system — install the dependencies in the default system-wide installation.
--installation=NAME — install the dependencies in a system-wide installation specified by NAME among those defined in /etc/flatpak/installations.d/. and fyi, using --installation=default is equivalent to using --system. 👑

💾 CACHING 💾

okay so flatpak-builder caches sources and partial build results in the state directory — which defaults to the .flatpak-builder subdirectory of the current directory. and if you use --keep-build-dirs, the build directories for each module are also stored here. little hoarder, love that for it 🐿️

It is safe to remove the state directory. it'll just force a full build next time you build. dramatic but honest 😭

🌈 EXAMPLES 🌈

$ flatpak-builder my-app-dir manifest.json

Example manifest file:

{
    "id": "org.test.TestApp",
    "runtime": "org.freedesktop.Platform",
    "runtime-version": "1.2",
    "sdk": "org.freedesktop.Sdk",
    "command": "test",
    "cleanup": [ "/include", "*.la" ],
    "build-options" : {
        "cflags": "-O2 -g",
        "cxxflags": "-O2 -g",
        "env": {
            "V": "1"
        },
        "arch": {
            "x86_64": {
                "cflags": "-O3 -g",
            }
        }
    },
    "modules": [
        {
            "name": "pygobject",
            "config-opts": [ "--disable-introspection" ],
            "sources": [
                {
                    "type": "archive",
                    "url": "http://ftp.gnome.org/pub/GNOME/sources/pygobject/2.28/pygobject-2.28.6.tar.xz",
                    "sha256": "fb8a1d4f665130a125011659bd347c7339c944232163dbb9a34fd0686577adb8"
                },
                {
                    "type": "patch",
                    "path": "required-pygobject-fix.patch"
                },
                {
                    "type": "file",
                    "path": "pygobject-extra-file",
                    "dest-filename": "extra-file"
                }
            ]
        },
        {
            "name": "babl",
            "build-options" : { "cxxflags": "-O2 -g -std=c++11" },
            "cleanup": [ "/bin" ],
            "sources": [
                {
                    "type": "git",
                    "url": "https://gitlab.gnome.org/GNOME/babl.git"
                }
            ]
        },
        {
            "name": "testapp",
            "sources": [
                {
                    "type": "bzr",
                    "url": "lp:testapp"
                }
            ]
        }
    ]
}

just copy that energy and you're building slay little apps in no time 💖

🫶 SEE ALSO 🫶

and that's the whole page, bestie!! 📖✨ this was brought to you by the flatpak crew, filed under FLATPAK-BUILDER(1) — so if you need to cite it, that's your source and your version tag right there. go build something cute, you've got this 💅👑🎀

📦 where this page comes from

arch rolling: flatpak-builder 1.4.12-1 · LGPL-2.1-or-later
ubuntu stonking: flatpak-builder 1.4.12-1
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-02: a language model's rewrite of the original, under its terms