flatpak-builder
Build Flatpak application bundles
TLDR
Build a Flatpak and export it to a new repository
Build a Flatpak and export it to the specified repository
Build a Flatpak and install it locally
Build and sign a Flatpak and export it to the specified repository
Run a shell inside of an application sandbox without installing it
SYNOPSIS
flatpak-builder [OPTIONS...] DIRECTORY MANIFEST
PARAMETERS
DIRECTORY
The directory to use as the build environment. This should be an empty directory.
MANIFEST
The path to the application manifest file (JSON or YAML).
--arch=ARCH
The architecture to build for (e.g., x86_64, i386, arm). Defaults to the host architecture.
--repo=REPO
The path to a local Flatpak repository to export the build to.
--bundle=BUNDLE
The path to create a Flatpak bundle at.
--force-clean
Force a clean build by removing the build directory before starting.
--no-cleanup
Do not clean up the build directory after the build is finished.
--require-version=VERSION
Require a specific version of Flatpak. Exit if the installed Flatpak is older.
--state-dir=DIRECTORY
Override the state directory used by flatpak-builder.
--user-only
Install user-only dependencies. Equivalent to passing --default-branch=app
to flatpak install
.
--verbose
Show verbose output.
--ostree-verbose
Show verbose ostree output.
--disable-updates
Disable update checking during the build.
--download-only
Only download the sources, do not build.
--build-only
Do not download sources, just build.
--finish-args=ARGS
Extra arguments to pass to flatpak build-finish
.
--export-args=ARGS
Extra arguments to pass to flatpak build-export
.
--gpg-sign=KEYID
GPG key ID to sign the commit with.
--timestamp=TIMESTAMP
Timestamp to use for the commit (seconds since epoch).
--default-branch=BRANCH
Override the default branch to use when installing dependencies.
DESCRIPTION
flatpak-builder
is a command-line tool used to build Flatpak applications from a declarative manifest file. It takes a manifest file (typically named org.example.YourApp.json
or org.example.YourApp.yml
) as input, which describes the application, its dependencies, and build instructions. flatpak-builder
then executes these instructions in a sandboxed environment to produce a Flatpak bundle or repository.
It handles dependency resolution, build system integration (e.g., Autotools, Meson, CMake), and ensures reproducible builds. The primary goal is to provide a reliable and automated way to create Flatpak packages suitable for distribution. flatpak-builder
is widely used by developers to package their applications for various Linux distributions through Flatpak.
CAVEATS
The DIRECTORY provided must be an empty directory. flatpak-builder
will create files and subdirectories within this directory. If the directory is not empty, the build may fail or produce unexpected results. Also building without internet connection can fail, if dependencies are not available locally.
MANIFEST FILE FORMAT
The manifest file is the core of the flatpak-builder
process. It specifies the application ID, runtime, SDK, sources, modules, and other build options. The format is typically JSON or YAML, offering a human-readable way to describe the build process. See the Flatpak documentation for detailed information on the manifest file format.
BUILD MODULES
A Flatpak application is typically built from multiple modules, each representing a component of the application. Each module specifies its sources, build system, and build commands. This modular approach allows for better dependency management and reuse of build configurations.
DEPENDENCY MANAGEMENT
flatpak-builder
automatically resolves and installs dependencies specified in the manifest file. It uses the configured Flatpak remotes to download the necessary runtimes, SDKs, and libraries. It allows you to specify dependencies from the application itself, dependencies from other flatpak packages. This greatly simplifies the process of creating self-contained Flatpak applications.
HISTORY
flatpak-builder
was created as part of the Flatpak project to simplify the process of building Flatpak applications. It provides a higher-level abstraction over the lower-level flatpak build
command, handling much of the complexity of dependency resolution and build system integration. Over time, it has evolved to support a wider range of build systems, architectures, and build options. Its usage has grown substantially as Flatpak has become a popular way to distribute applications on Linux.
SEE ALSO
flatpak(1), flatpak-build(1)