flatpak-builder

Build a Flatpak and export it to a new repository

$ flatpak-builder [path/to/build_directory] [path/to/manifest]

$ flatpak-builder --repo [repository_name] [path/to/build_directory] [path/to/manifest]

$ flatpak-builder --install [path/to/build_directory] [path/to/manifest]

$ flatpak-builder --gpg-sign [key_id] --repo [repository_name] [path/to/manifest]

$ flatpak-builder --run [path/to/build_directory] [path/to/manifest] [sh]

flatpak-builder [OPTION…] [BUILDDIR] MANIFEST [VERB…]

--force-clean
    Discard all previous build state and start fresh

--install[=always|true|if-needed|false]
    Automatically install result after successful build

--repo=DIR
    OSTree repository directory to use

--state-dir=DIR
    Directory for build state files

--stop-at=STAGE
    Stop after reaching specified build stage

--share=SHARE
    Share directory with host (network,ipc)

--jobs=NUM
    Run NUM jobs in parallel during builds

--ccache
    Use ccache for compilations

--no-cache
    Disable build caches

--no-debuginfo
    Skip generating debug information

--no-deploy
    Do not deploy to runtime

--prune
    Prune unused objects from repo after build

--test
    Run tests after build

--test-args=ARGS
    Arguments to pass to tests

--update-only
    Only update if newer commit available

--user
    Install to user installation

--run
    Run the built application

--keep-build-dirs=NUM
    Keep NUM most recent build directories

--help
    Show help and exit

--version
    Show version and exit

BUILDDIR
    Build directory (optional, defaults to current dir)

MANIFEST
    Path to JSON/YAML manifest file (required)

VERB…
    Build verbs like clean, build, bundle, shell (optional)

flatpak-builder is a powerful tool for constructing Flatpak applications and runtimes from a declarative manifest file, typically in JSON format. It streamlines the entire build process, including source fetching, dependency resolution, compilation, bundling, and optional deployment into a sandboxed environment.

Flatpak enables universal Linux app distribution, ensuring consistent runtime across distros via OSTree repositories. The manifest defines modules, SDKs, sources (git, tarballs, archives), patches, build commands, and finish-args for permissions.

The tool supports multi-stage builds, where each module builds in isolation using specified SDKs. It handles caches, debug info, and pruning for efficiency. Developers use it iteratively with verbs like clean, build, shell for testing.

Example workflow: Create myapp.json, run flatpak-builder --repo=repo build myapp.json to build, then --install --bundle to package and deploy. It integrates with CI/CD for automated builds, supporting remote repositories and updates.

Key benefits include sandboxing for security, extensibility via extensions, and runtime isolation, making it ideal for GUI apps, servers, and more.

Requires Flatpak, OSTree, and build dependencies installed. Needs significant disk space for caches/repos. Root or user repo access may be required. Not for production deploys without review.

clean - Clean build dir
build - Build modules
bundle - Create .flatpak bundle
shell - Run shell in sandbox

See flatpak-manifest(5). Basic structure: {'app-id': 'org.example.App', 'runtime': 'org.gnome.Platform', 'sdk': 'org.gnome.Sdk', 'modules': [{'name': 'app', 'buildsystem': 'simple', 'buildcommands': ['make install']}]}

Originated from Endless Computers' xdg-app project in 2015, evolved into Flatpak in 2016 under Alexander Larsson and Collabora/Freedesktop.org. flatpak-builder added for manifest-based builds, maturing with Flatpak 0.10+; now core to Flathub ecosystem with widespread adoption.

flatpak(1), flatpak-build(1), flatpak-build-bundle(1), flatpak-manifest(5), ostree(1)