Flatpak Command Reference

Version 0.6.7

+ Flatpak comes with a rich commandline interface. +

Table of Contents

flatpak install — Install an application or runtime
flatpak update — Update a runtime
flatpak uninstall — Uninstall an application or runtime
flatpak list — List installed applications and/or runtimes
flatpak info — Show information about installed application and/or runtime
flatpak run — Run an application
flatpak override — Override application requirements
flatpak enter — Enter an application
flatpak document-export — Export a file to a sandboxed application
flatpak document-unexport — Stop exporting a file
flatpak document-info — Show information about exported files
flatpak document-list — List exported files
flatpak remote-add — Add a remote repository
flatpak remote-modify — Modify a remote repository
flatpak remote-delete — Delete a remote repository
flatpak remote-list — List remote repositories
flatpak remote-ls — Show available runtimes and applications
flatpak build-init — Initialize a build directory
flatpak build — Build in a directory
flatpak build-finish — Finalize a build directory
flatpak build-export — Create a repository from a build directory
flatpak build-bundle — Create a single-file bundle from a local repository
flatpak build-import-bundle — Import a file bundle into a local repository
flatpak build-update-repo — Create a repository from a build directory
flatpak build-sign — Sign an application or runtime
flatpak-builder — Help build application dependencies
flatpak metadata — Information about an application or runtime
flatpak make-current — Make a specific version of an app current

Name

flatpak-install — Install an application or runtime

Synopsis

flatpak install [OPTION...] REMOTE NAME [BRANCH]

flatpak install [OPTION...] --bundle FILENAME

Description

+ Installs an application or runtime. REMOTE must name + an existing remote and NAME is the name of the + application or runtime to install. Optionally, BRANCH can + be specified to install a branch other than the default branch. This required + if there are multiple matches in the selected remote. +

+ By default this looks for both apps and runtime with the given NAME in + the specified REMOTE , but you can limit this by using the --app or --runtime option. +

+ Note that flatpak allows one to have multiple branches of an application and runtimes + installed and used at the same time. However, only version of an application one can be current, + meaning its exported files (for instance desktop files and icons) are + visible to the host. The last installed version is made current by + default, but you can manually change with make-current. +

+ Unless overridden with the --user option, this command creates a + system-wide installation. +

+ The alternative form of the command installs an application from a + single-file bundle instead of a configured remote. Such bundles can + be created with the flatpak build-bundle command. +

Options

The following options are understood:

-h, --help: + Show help options and exit. +
--bundle: + Install from a bundle file instead + of a configured remote. +
--user: + Create a per-user installation. +
--user: + Create a per-user installation. +
--system: + Create a system-wide installation. +
--arch=ARCH: + The architecture to install for. +
--subpath=PATH: + Install only a subpath of the ref. This is mainly used to install a subset of locales. + This can be added multiple times to install multiple subpaths., +
--no-deploy: + Download the latest version, but don't deploy it. +
--no-pull: + Don't download the latest version, deploy it whatever is locally available. +
--no-related: + Don't download related extensions, such as the locale data. +
--app: + Only look for an app with the given name. +
--runtime: + Only look for an runtime with the given name. +
-v, --verbose: + Print debug information during command processing. +
--version: + Print version information and exit. +

Examples

+ $ flatpak --user install test-repo org.gnome.GEdit +

Name

flatpak-update — Update a runtime

Synopsis

flatpak update [OPTION...] [NAME] [BRANCH]

Description

+ Updates an application or runtime. NAME is the + name of an installed application or runtime. Optionally, + BRANCH can be specified to update a + specific branch, otherwise all installed branches are updated. If + no NAME is given, then everything installed + is updated. +

+ By default this looks for both installed applications and + runtimes, but you can limit this by using the --app or + --runtime option. +

+ Normally, this command updates the application to the tip + of its branch. But it is possible to check out another commit, + with the --commit option. +

+ Note that updating a is different from installing + a different branch, and runtime updates are expected to keep + strict compatibility. If an application update does cause + a problem, it is possible to go back to the previous + version, with the --commit option. +

+ Unless overridden with the --user option, this command updates + a system-wide installation. +

Options

The following options are understood:

-h, --help: + Show help options and exit. +
--user: + Update a per-user installation. +
--system: + Update a system-wide installation. +
--arch=ARCH: + The architecture to update for. +
--subpath=PATH: + Install only a subpath of the ref. This is mainly used to install a subset of locales. + This can be added multiple times to install multiple subpaths. + If this is not specified the subpaths specified at install time are reused. +
--commit=COMMIT: + Update to this commit, instead of the tip of the branch. +
--no-deploy: + Download the latest version, but don't deploy it. +
--no-pull: + Don't download the latest version, deploy it whatever is locally available. +
--no-related: + Don't download related extensions, such as the locale data. +
--app: + Only look for an app with the given name. +
--runtime: + Only look for an runtime with the given name. +
-v, --verbose: + Print debug information during command processing. +
--version: + Print version information and exit. +

Examples

+ $ flatpak --user update org.gnome.GEdit +

Name

flatpak-uninstall — Uninstall an application or runtime

Synopsis

flatpak uninstall [OPTION...] NAME [BRANCH]

Description

+ Uninstalls an application or runtime. The NAME , + ARCH and BRANCH + arguments must identify an installed application. + If BRANCH is not specified, it defaults + to whatever is installed, unless there are multiple versions, then you + have to specify a branch. +

+ By default this looks for both installed apps and runtime + with the given NAME , but you can + limit this by using the --app or --runtime option. +

+ Normally, this command removes the ref for this application/runtime from the + local OSTree repository and purges and objects that are no longer + needed to free up disk space. If the same application is later + reinstalled, the objects will be pulled from the remote repository + again. The --keep-ref option can be used to prevent this. +

+ If all branches of the application/runtime are removed, this command + also purges the data directory for the application. +

+ Unless overridden with the --user option, this command updates + a system-wide installation. +

Options

The following options are understood:

-h, --help: + Show help options and exit. +
--keep-ref: + Keep the ref for the application and the objects belonging to it + in the local repository. +
--user: + Remove a per-user installation. +
--system: + Remove a system-wide installation. +
--arch=ARCH: + The architecture to uninstall, instead of the architecture of + the host system. +
--app: + Only look for an app with the given name. +
--runtime: + Only look for an runtime with the given name. +
--no-related: + Don't uninstall related extensions, such as the locale data. +
-v, --verbose: + Print debug information during command processing. +
--version: + Print version information and exit. +

Examples

+ $ flatpak --user uninstall org.gnome.GEdit +

Name

flatpak-list — List installed applications and/or runtimes

Synopsis

flatpak list [OPTION...]

Description

+ Lists the names of the installed applications and/or runtime. +

+ By default, both per-user and system-wide installations + are shown. Use the --user or --system options to change + this. +

+ By default this lists the installed apps, but you can + change this by using the --app or --runtime option. +

Options

The following options are understood:

-h, --help: + Show help options and exit. +
--user: + List per-user installations. +
--system: + List system-wide installations. +
--show-details: + Show arches and branches, in addition to the application names. +
--app: + List applications. +
--runtime: + List runtimes. +
-v, --verbose: + Print debug information during command processing. +
--version: + Print version information and exit. +

Examples

+ $ flatpak --user list +

+org.gnome.Builder
+org.freedesktop.glxgears
+org.gnome.MyApp
+org.gnome.GEdit
+

Name

flatpak-info — Show information about installed application and/or runtime

Synopsis

flatpak info [OPTION...] NAME [BRANCH]

Description

+ Show info about and installed application and/or runtime. +

+ By default, both per-user and system-wide installations + are queried. Use the --user or --system options to change + this. +

+ By default this queries the installed apps and runtimes, but you can + limit this by using the --app or --runtime option. +

Options

The following options are understood:

-h, --help: + Show help options and exit. +
--user: + Query per-user installations. +
--system: + Query system-wide installations. +
--app: + Query for applications. +
--runtime: + Query for runtimes. +
-r, --show-ref: + Show the installed ref. +
-o, --show-origin: + Show the remote the ref is installed from. +
-c, --show-commit: + Show the installed commit id. +
-v, --verbose: + Print debug information during command processing. +
--version: + Print version information and exit. +

Examples

+ $ flatpak --user list +

+org.gnome.Builder
+org.freedesktop.glxgears
+org.gnome.MyApp
+org.gnome.GEdit
+

Name

flatpak-run — Run an application

Synopsis

flatpak run [OPTION...] APP [ARG...]

Description

+ Runs an application in a sandboxed environment. + APP must name an installed application. + Extra arguments are passed on to the application. +

+ flatpak creates a sandboxed environment for the application to run in + by mounting the right runtime at /usr and a writable + directory at /var, whose content is preserved between + application runs. The application itself is mounted at /app. +

+ The details of the sandboxed environment are controlled by the application + metadata and various options like --share and --socket that are passed to the run + command: Access is allowed if it was requested either in the application + metadata file or with an option and the user hasn't overridden it. +

Options

The following options are understood:

-h, --help: + Show help options and exit. +
-v, --verbose: + Print debug information during command processing. +
--version: + Print version information and exit. +
--arch=ARCH: + The architecture to install for. +
--command=COMMAND: + The command to run instead of the one listed in the application metadata. +
--branch=BRANCH: + The branch to use. +
-d, --devel: + Use the devel runtime that is specified in the application metadata instead of the regular runtime, and use a seccomp profile that is less likely to break development tools. +
--runtime=RUNTIME: + Use this runtime instead of the one that is specified in the application metadata. + This is a full tuple, like for example org.freedesktop.Sdk/x86_64/1.2 , but + partial tuples are allowed. Any empty or missing parts are filled in with the corresponding + values specified by the app. +
--runtime-version=VERSION: + Use this version of the runtime instead of the one that is specified in the application metadata. + This overrides any version specified with the --runtime option. +
--share=SUBSYSTEM: + Share a subsystem with the host session. This overrides + the Context section from the application metadata. + SUBSYSTEM must be one of: network, ipc. + This option can be used multiple times. +
--unshare=SUBSYSTEM: + Don't share a subsystem with the host session. This overrides + the Context section from the application metadata. + SUBSYSTEM must be one of: network, ipc. + This option can be used multiple times. +
--socket=SOCKET: + Expose a well known socket to the application. This overrides to + the Context section from the application metadata. + SOCKET must be one of: x11, wayland, pulseaudio, system-bus, session-bus. + This option can be used multiple times. +
--nosocket=SOCKET: + Don't expose a well known socket to the application. This overrides to + the Context section from the application metadata. + SOCKET must be one of: x11, wayland, pulseaudio, system-bus, session-bus. + This option can be used multiple times. +
--device=DEVICE: + Expose a device to the application. This overrides to + the Context section from the application metadata. + DEVICE must be one of: dri, all. + This option can be used multiple times. +
--nodevice=DEVICE: + Don't expose a device to the application. This overrides to + the Context section from the application metadata. + DEVICE must be one of: dri, all. + This option can be used multiple times. +
--filesystem=FS: + Allow the application access to a subset of the filesystem. + This overrides to the Context section from the application metadata. + FS can be one of: home, host, xdg-desktop, xdg-documents, xdg-download + xdg-music, xdg-pictures, xdg-public-share, xdg-templates, xdg-videos, xdg-run, + an absolute path, or a homedir-relative path like ~/dir or paths + relative to the xdg dirs, like xdg-download/subdir. + This option can be used multiple times. +
--env=VAR=VALUE: + Set an environment variable in the application. + This overrides to the Context section from the application metadata. + This option can be used multiple times. +
--own-name=NAME: + Allow the application to own the well known name NAME on the session bus. + If NAME ends with .*, it allows the application to own all matching names. + This overrides to the Context section from the application metadata. + This option can be used multiple times. +
--talk-name=NAME: + Allow the application to talk to the well known name NAME on the session bus. + If NAME ends with .*, it allows the application to talk to all matching names. + This overrides to the Context section from the application metadata. + This option can be used multiple times. +
--system-own-name=NAME: + Allow the application to own the well known name NAME on the system bus. + If NAME ends with .*, it allows the application to own all matching names. + This overrides to the Context section from the application metadata. + This option can be used multiple times. +
--system-talk-name=NAME: + Allow the application to talk to the well known name NAME on the system bus. + If NAME ends with .*, it allows the application to talk to all matching names. + This overrides to the Context section from the application metadata. + This option can be used multiple times. +
--persist=FILENAME: + If the application doesn't have access to the real homedir, make the (homedir-relative) path + FILENAME a bind mount to the corresponding path in the per-application directory, + allowing that location to be used for persistent data. + This overrides to the Context section from the application metadata. + This option can be used multiple times. +
--no-desktop: + Don't require a running session, meaning that no cgroups creation will happen. This can be + useful for certain scenarios when you might want to run a flatpak without a valid user + session available (e.g. from a socket-activated systemd service), and not having a + properly sandboxed environment is not an issue. +
--log-session-bus: + Log session bus traffic. This can be useful to see what access you need to allow in + your D-Bus policy. +
--log-system-bus: + Log system bus traffic. This can be useful to see what access you need to allow in + your D-Bus policy. +

Examples

+ $ flatpak run org.gnome.GEdit +

+ $ flatpak run --devel --command=bash org.gnome.Builder +

Name

flatpak-override — Override application requirements

Synopsis

flatpak override [OPTION...] APP

Description

+ Overrides the application specified runtime requirements. This can be used + to grant a sandboxed application more or less resources than it requested. +

+ By default the application gets access to the resources it + requested when it is started. But the user can override it + on a particular instance by specifying extra arguments to + flatpak run, or every time by using flatpak override. +

Options

The following options are understood:

-h, --help: + Show help options and exit. +
--share=SUBSYSTEM: + Share a subsystem with the host session. This overrides + the Context section from the application metadata. + SUBSYSTEM must be one of: network, ipc. + This option can be used multiple times. +
--unshare=SUBSYSTEM: + Don't share a subsystem with the host session. This overrides + the Context section from the application metadata. + SUBSYSTEM must be one of: network, ipc. + This option can be used multiple times. +
--socket=SOCKET: + Expose a well-known socket to the application. This overrides to + the Context section from the application metadata. + SOCKET must be one of: x11, wayland, pulseaudio, system-bus, session-bus. + This option can be used multiple times. +
--nosocket=SOCKET: + Don't expose a well-known socket to the application. This overrides to + the Context section from the application metadata. + SOCKET must be one of: x11, wayland, pulseaudio, system-bus, session-bus. + This option can be used multiple times. +
--device=DEVICE: + Expose a device to the application. This overrides to + the Context section from the application metadata. + DEVICE must be one of: dri, all. + This option can be used multiple times. +
--nodevice=DEVICE: + Don't expose a device to the application. This overrides to + the Context section from the application metadata. + DEVICE must be one of: dri, all. + This option can be used multiple times. +
--filesystem=FS: + Allow the application access to a subset of the filesystem. + This overrides to the Context section from the application metadata. + FS can be one of: home, host, xdg-desktop, xdg-documents, xdg-download + xdg-music, xdg-pictures, xdg-public-share, xdg-templates, xdg-videos, xdg-run, + an absolute path, or a homedir-relative path like ~/dir or paths + relative to the xdg dirs, like xdg-download/subdir. + This option can be used multiple times. +
--env=VAR=VALUE: + Set an environment variable in the application. + This overrides to the Context section from the application metadata. + This option can be used multiple times. +
--own-name=NAME: + Allow the application to own the well-known name NAME on the session bus. + This overrides to the Context section from the application metadata. + This option can be used multiple times. +
--talk-name=NAME: + Allow the application to talk to the well-known name NAME on the session bus. + This overrides to the Context section from the application metadata. + This option can be used multiple times. +
--system-own-name=NAME: + Allow the application to own the well known name NAME on the system bus. + If NAME ends with .*, it allows the application to own all matching names. + This overrides to the Context section from the application metadata. + This option can be used multiple times. +
--system-talk-name=NAME: + Allow the application to talk to the well known name NAME on the system bus. + If NAME ends with .*, it allows the application to talk to all matching names. + This overrides to the Context section from the application metadata. + This option can be used multiple times. +
--persist=FILENAME: + If the application doesn't have access to the real homedir, make the (homedir-relative) path + FILENAME a bind mount to the corresponding path in the per-application directory, + allowing that location to be used for persistent data. + This overrides to the Context section from the application metadata. + This option can be used multiple times. +
-v, --verbose: + Print debug information during command processing. +
--version: + Print version information and exit. +

Examples

+ $ flatpak override --nosocket=wayland org.gnome.GEdit +

+ $ flatpak override --filesystem=home org.mozilla.Firefox +

Name

flatpak-enter — Enter an application

Synopsis

flatpak enter [OPTION...] MONITORPID COMMAND [ARG...]

Description

+ Enter a running sandbox. + MONITORPID must be the pid of the monitor process for a running sandbox. + COMMAND is the command to run in the sandbox. + Extra arguments are passed on to the command. +

+ This creates a new process within the running sandbox, with the same environment. This is useful + when you want to debug a problem with a running application. +

Options

The following options are understood:

-h, --help: + Show help options and exit. +
-v, --verbose: + Print debug information during command processing. +
--version: + Print version information and exit. +

Examples

+ $ flatpak enter 15345 sh +

Name

flatpak-document-export — Export a file to a sandboxed application

Synopsis

flatpak document-export [OPTION...] FILE

Description

+ Creates a document id for a local file that can be exposed to + sandboxed applications, allowing them access to files that they + would not otherwise see. The exported files are exposed in a + fuse filesystem at /run/user/$UID/doc/. +

+ This command also lets you modify the per-application + permissions of the documents, granting or revoking access + to the file on a per-application basis. +

Options

The following options are understood:

-h, --help: + Show help options and exit. +
--unique: Don't reuse an existing document id + for the file. This makes it safe to later remove the + document when you're finished with it. +
--transient: + The document will only exist for the length of + the session. This is useful for temporary grants. +
--app=APPID: + Grant read access to the specified application. The + --allow and --forbid options can be used to grant + or remove additional privileges. + This option can be used multiple times. +
--allow-read: + Grant read access to the applications specified with --app. + This defaults to TRUE. +
--forbid-read: + Revoke read access for the applications specified with --app. +
--allow-write: + Grant write access to the applications specified with --app. +
--forbid-write: + Revoke write access for the applications specified with --app. +
--allow-delete: + Grant the ability to remove the document from the document portal to the applications specified with --app. +
--forbid-delete: + Revoke the ability to remove the document from the document portal from the applications specified with --app. +
--allow-grant-permission: + Grant the ability to grant further permissions to the applications specified with --app. +
--forbid-grant-permission: + Revoke the ability to grant further permissions for the applications specified with --app. +
-v, --verbose: + Print debug information during command processing. +
--version: + Print version information and exit. +

Examples

+ $ flatpak document-export --app=org.gnome.GEdit ~/test.txt +

+/run/user/1000/doc/e52f9c6a/test.txt
+

Name

flatpak-document-unexport — Stop exporting a file

Synopsis

flatpak document-export [OPTION...] FILE

Description

+ Removes the document id for the file from the + document portal. This will make the document unavailable + to all sandboxed applications. +

Options

The following options are understood:

-h, --help: + Show help options and exit. +
-v, --verbose: + Print debug information during command processing. +
--version: + Print version information and exit. +

Name

flatpak-document-info — Show information about exported files

Synopsis

flatpak document-info [OPTION...] FILE

Description

+ Shows information about an exported file, such as the + document id, the fuse path, the original location in the + filesystem, and the per-application permissions. +

+ FILE can either be a file in the fuse filesystem at /run/user/$UID/doc/, + or a file anywhere else. +

Options

The following options are understood:

-h, --help: + Show help options and exit. +
-v, --verbose: + Print debug information during command processing. +
--version: + Print version information and exit. +

Examples

+ $ flatpak document-info ~/Sources/gtk/gail-3.0.pc +

+id: dd32c34a
+path: /run/user/1000/doc/dd32c34a/gail-3.0.pc
+origin: /home/mclasen/Sources/gtk/gail-3.0.pc
+permissions:
+        org.gnome.gedit read, write
+

Name

flatpak-document-list — List exported files

Synopsis

flatpak document-list [OPTION...] [APPID]

Description

+ Lists exported files, with their document id and the + full path to their origin. If an APPID is specified, + only the files exported to this app are listed. +

Options

The following options are understood:

-h, --help: + Show help options and exit. +
-v, --verbose: + Print debug information during command processing. +
--version: + Print version information and exit. +

Name

flatpak-remote-add — Add a remote repository

Synopsis

flatpak remote-add [OPTION...] NAME LOCATION

Description

+ Adds a remote repository to the flatpak repository configuration. + NAME is the name for the new remote, and + LOCATION is the url or pathname for the repository. +

+ Unless overridden with the --user option, this command changes + the system-wide configuration. +

Options

The following options are understood:

-h, --help: + Show help options and exit. +
--user: + Modify the per-user configuration. +
--system: + Modify the system-wide configuration. +
--no-gpg-verify: + Disable GPG verification for the added remote. +
--prio=PRIO: + Set the priority for the remote. Default is 1, higher is more prioritized. This is + mainly used for graphical installation tools. +
--no-enumerate: + Mark the remote as not enumerated. This means the remote will + not be used to list applications, for instance in graphical + installation tools. +
--if-not-exists: + Do nothing if the provided remote already exists. +
--disable: + Disable the added remote. +
--title=TITLE: + A title for the remote, e.g. for display in a UI. +
--gpg-import=FILE: + Import gpg keys from the specified keyring file as + trusted for the new remote. If the file is - the + keyring is read from standard input. +
-v, --verbose: + Print debug information during command processing. +
--version: + Print version information and exit. +

Examples

+ $ flatpak --user remote-add --no-gpg-verify test-repo https://people.gnome.org/~alexl/gnome-sdk/repo/ +

Name

flatpak-remote-modify — Modify a remote repository

Synopsis

flatpak remote-modify [OPTION...] NAME

Description

+ Modifies options for an existing remote repository in the flatpak repository configuration. + NAME is the name for the remote. +

+ Unless overridden with the --user option, this command changes + the system-wide configuration. +

Options

The following options are understood:

-h, --help: + Show help options and exit. +
--user: + Modify the per-user configuration. +
--system: + Modify the system-wide configuration. +
--no-gpg-verify: + Disable GPG verification for the added remote. +
--gpg-verify: + Enable GPG verification for the added remote. +
--prio=PRIO: + Set the priority for the remote. Default is 1, higher is more prioritized. This is + mainly used for graphical installation tools. +
--no-enumerate: + Mark the remote as not enumerated. This means the remote will + not be used to list applications, for instance in graphical + installation tools. +
--disable: + Disable the remote. Disabled remotes will not be automatically updated from. +
--enable: + Enable the remote. +
--enumerate: + Mark the remote as enumerated. This means the remote will + be used to list applications, for instance in graphical + installation tools. +
--title=TITLE: + A title for the remote, e.g. for display in a UI. +
--gpg-import=FILE: + Import gpg keys from the specified keyring file as + trusted for the new remote. If the file is - the + keyring is read from standard input. +
-v, --verbose: + Print debug information during command processing. +
--version: + Print version information and exit. +

Examples

+ $ flatpak --user remote-modify --no-gpg-verify test-repo +

Name

flatpak-remote-delete — Delete a remote repository

Synopsis

flatpak remote-delete [OPTION...] NAME

Description

+ Removes a remote repository from the flatpak repository configuration. + NAME is the name of an existing remote. +

+ Unless overridden with the --user option, this command changes + the system-wide configuration. +

Options

The following options are understood:

-h, --help: + Show help options and exit. +
--user: + Modify the per-user configuration. +
--system: + Modify the system-wide configuration. +
--force: + Remove remote even if its in use by installed apps or runtimes. +
-v, --verbose: + Print debug information during command processing. +
--version: + Print version information and exit. +

Examples

+ $ flatpak --user remote-delete dried-raisins +

Name

flatpak-remote-list — List remote repositories

Synopsis

flatpak remote-list [OPTION...]

Description

+ Lists the known remote repositories, in priority order. +

+ By default, both per-user and system-wide installations + are shown. Use the --user or --system options to change + this. +

Options

The following options are understood:

-h, --help: + Show help options and exit. +
--user: + Show the per-user configuration. +
--system: + Show the system-wide configuration. +
--show-details: + Show more information each repository in addition to the name. +
--show-disabled: + Show disabled repos. +
-v, --verbose: + Print debug information during command processing. +
--version: + Print version information and exit. +

Examples

+ $ flatpak remote-list --user --show-details +

+testrepo	Test Repository	 http://209.132.179.91/repo/ no-gpg-verify
+

Name

flatpak-remote-ls — Show available runtimes and applications

Synopsis

flatpak remote-ls [OPTION...] REMOTE

Description

+ Shows runtimes and applications that are available in the + remote repository with the name REMOTE . + You can find all configured remote repositories with flatpak list-repos. +

+ Unless overridden with the --user option, this command uses + the system-wide configuration. +

Options

The following options are understood:

-h, --help: + Show help options and exit. +
--user: + Use the per-user configuration. +
--system: + Use the system-wide configuration. +
-d, --show-details: + Show arches, branches and commit ids, in addition to the names. +
--runtime: + Show only runtimes, omit applications. +
--app: + Show only applications, omit runtimes. +
--updates: + Show only those which have updates available. +
--arch=ARCH: + Show only those matching the specied architecture. By default, only + supported architectures are shown. Use --arch=* to show all archtectures. +
-v, --verbose: + Print debug information during command processing. +
--version: + Print version information and exit. +

Examples

+ $ flatpak --user remote-ls --only-apps testrepo +

+org.gnome.Builder
+org.freedesktop.glxgears
+

Name

flatpak-build-init — Initialize a build directory

Synopsis

flatpak build-init [OPTION...] DIRECTORY APPNAME SDK RUNTIME [BRANCH]

Description

+ Initializes a directory for building an application. + DIRECTORY is the name of the directory. + APPNAME is the application id of the app + that will be built. + SDK and RUNTIME + specify the sdk and runtime that the application should be built + against and run in. +

+ The result of this command is that a metadata + file is created inside the given directory. Additionally, empty + files and var subdirectories + are created. +

+ It is an error to run build-init on a directory that has already + been initialized as a build directory. +

Options

The following options are understood:

-h, --help: + Show help options and exit. +
--arch=ARCH: + The architecture to use. +
-v, --var=RUNTIME: + Initialize var from the named runtime. +
-w, --writable-sdk: + Initialize /usr with a copy of the sdk, which is writable during flatpak build. This can be used + if you need to install build tools in /usr during the build. This is stored in the + usr subdirectory of the app dir, but will not be part of the final + app. +
--tag=TAG: + Add a tag to the metadata file. +
--sdk-extension=EXTENSION: + When using --writable-sdk, in addition to the sdk, also install the specified extension. +
--sdk-dir: + Specify a custom subdirectory to use instead of usr for --writable-sdk. +
--update: + Re-initialize the sdk and var, don't fail if already initialized. +
--verbose: + Print debug information during command processing. +
--version: + Print version information and exit. +

Examples

+ $ flatpak build-init /build/my-app org.gnome.Sdk org.gnome.Platform 3.16 +

Name

flatpak-build — Build in a directory

Synopsis

flatpak build [OPTION...] DIRECTORY [COMMAND [ARG...]]

Description

+ Runs a build command in a directory. DIRECTORY + must have been initialized with flatpak build-init. +

+ The sdk that is specified in the metadata file + in the directory is mounted at /usr and the + files and var subdirectories + are mounted at /app and /var, + respectively. They are writable, and their contents are preserved between + build commands, to allow accumulating build artifacts there. +

Options

The following options are understood:

-h, --help: + Show help options and exit. +
-v, --verbose: + Print debug information during command processing. +
--version: + Print version information and exit. +
-r, --runtime: + Use the non-devel runtime that is specified in the application metadata instead of the devel runtime. +
--bind-mount=DEST=SOURCE: + Add a custom bind mount in the build namespace. Can be specified multiple times. +
--build-dir=PATH: + Start the build in this directory (default is in the current directory). +
--share=SUBSYSTEM: + Share a subsystem with the host session. This overrides + the Context section from the application metadata. + SUBSYSTEM must be one of: network, ipc. + This option can be used multiple times. +
--unshare=SUBSYSTEM: + Don't share a subsystem with the host session. This overrides + the Context section from the application metadata. + SUBSYSTEM must be one of: network, ipc. + This option can be used multiple times. +
--socket=SOCKET: + Expose a well-known socket to the application. This overrides to + the Context section from the application metadata. + SOCKET must be one of: x11, wayland, pulseaudio, system-bus, session-bus. + This option can be used multiple times. +
--nosocket=SOCKET: + Don't expose a well-known socket to the application. This overrides to + the Context section from the application metadata. + SOCKET must be one of: x11, wayland, pulseaudio, system-bus, session-bus. + This option can be used multiple times. +
--device=DEVICE: + Expose a device to the application. This overrides to + the Context section from the application metadata. + DEVICE must be one of: dri, all. + This option can be used multiple times. +
--nodevice=DEVICE: + Don't expose a device to the application. This overrides to + the Context section from the application metadata. + DEVICE must be one of: dri, all. + This option can be used multiple times. +
--filesystem=FILESYSTEM[:ro]: + Allow the application access to a subset of the filesystem. + This overrides to the Context section from the application metadata. + FILESYSTEM can be one of: home, host, xdg-desktop, xdg-documents, xdg-download + xdg-music, xdg-pictures, xdg-public-share, xdg-templates, xdg-videos, + an absolute path, or a homedir-relative path like ~/dir. + The optional :ro suffix indicates that the location will be read-only. + This option can be used multiple times. +
--nofilesystem=FILESYSTEM: + Remove access to the specified subset of the filesystem from + the application. This overrides to the Context section from the + application metadata. + FILESYSTEM can be one of: home, host, xdg-desktop, xdg-documents, xdg-download + xdg-music, xdg-pictures, xdg-public-share, xdg-templates, xdg-videos, + an absolute path, or a homedir-relative path like ~/dir. + This option can be used multiple times. +
--env=VAR=VALUE: + Set an environment variable in the application. + This overrides to the Context section from the application metadata. + This option can be used multiple times. +
--own-name=NAME: + Allow the application to own the well-known name NAME on the session bus. + This overrides to the Context section from the application metadata. + This option can be used multiple times. +
--talk-name=NAME: + Allow the application to talk to the well-known name NAME on the session bus. + This overrides to the Context section from the application metadata. + This option can be used multiple times. +
--system-own-name=NAME: + Allow the application to own the well-known name NAME on the system bus. + This overrides to the Context section from the application metadata. + This option can be used multiple times. +
--system-talk-name=NAME: + Allow the application to talk to the well-known name NAME on the system bus. + This overrides to the Context section from the application metadata. + This option can be used multiple times. +
--persist=FILENAME: + If the application doesn't have access to the real homedir, make the (homedir-relative) path + FILENAME a bind mount to the corresponding path in the per-application directory, + allowing that location to be used for persistent data. + This overrides to the Context section from the application metadata. + This option can be used multiple times. +

Examples

+ $ flatpak build /build/my-app rpmbuild my-app.src.rpm +

Name

flatpak-build-finish — Finalize a build directory

Synopsis

flatpak build-finish [OPTION...] DIRECTORY

Description

+ Finalizes a build directory, to prepare it for exporting. + DIRECTORY is the name of the directory. +

+ The result of this command is that desktop files, icons and + D-Bus service files from the files subdirectory + are copied to a new export subdirectory. In the + metadata file, the command key is set in the + [Application] group, and the supported keys in the [Environment] + group are set according to the options. +

+ You should review the exported files and the application metadata + before creating and distributing an application bundle. +

+ It is an error to run build-finish on a directory that has not + been initialized as a build directory, or has already been finalized. +

Options

The following options are understood:

-h, --help: + Show help options and exit. +
--command=COMMAND: + The command to use. If this option is not specified, + the first executable found in files/bin + is used. +
--share=SUBSYSTEM: + Share a subsystem with the host session. This updates + the [Context] group in the metadata. + SUBSYSTEM must be one of: network, ipc. + This option can be used multiple times. +
--unshare=SUBSYSTEM: + Don't share a subsystem with the host session. This updates + the [Context] group in the metadata. + SUBSYSTEM must be one of: network, ipc. + This option can be used multiple times. +
--socket=SOCKET: + Expose a well known socket to the application. This updates + the [Context] group in the metadata. + SOCKET must be one of: x11, wayland, pulseaudio, system-bus, session-bus. + This option can be used multiple times. +
--nosocket=SOCKET: + Don't expose a well known socket to the application. This updates + the [Context] group in the metadata. + SOCKET must be one of: x11, wayland, pulseaudio, system-bus, session-bus. + This option can be used multiple times. +
--device=DEVICE: + Expose a device to the application. This updates + the [Context] group in the metadata. + DEVICE must be one of: dri, all. + This option can be used multiple times. +
--nodevice=DEVICE: + Don't expose a device to the application. This updates + the [Context] group in the metadata. + DEVICE must be one of: dri, all. + This option can be used multiple times. +
--filesystem=FS: + Allow the application access to a subset of the filesystem. + This updates the [Context] group in the metadata. + FS can be one of: home, host, xdg-desktop, xdg-documents, xdg-download + xdg-music, xdg-pictures, xdg-public-share, xdg-templates, xdg-videos, xdg-run, + an absolute path, or a homedir-relative path like ~/dir or paths + relative to the xdg dirs, like xdg-download/subdir. + This option can be used multiple times. +
--env=VAR=VALUE: + Set an environment variable in the application. + This updates the [Environment] group in the metadata. + This overrides to the Context section from the application metadata. + This option can be used multiple times. +
--own-name=NAME: + Allow the application to own the well known name NAME on the session bus. + If NAME ends with .*, it allows the application to own all matching names. + + This updates the [Session Bus Policy] group in the metadata. + This option can be used multiple times. +
--talk-name=NAME: + Allow the application to talk to the well known name NAME on the session bus. + If NAME ends with .*, it allows the application to talk to all matching names. + This updates the [Session Bus Policy] group in the metadata. + This option can be used multiple times. +
--system-own-name=NAME: + Allow the application to own the well known name NAME on the system bus. + If NAME ends with .*, it allows the application to own all matching names. + This updates the [System Bus Policy] group in the metadata. + This option can be used multiple times. +
--system-talk-name=NAME: + Allow the application to talk to the well known name NAME on the system bus. + If NAME ends with .*, it allows the application to talk to all matching names. + This updates the [System Bus Policy] group in the metadata. + This option can be used multiple times. +
--persist=FILENAME: + If the application doesn't have access to the real homedir, make the (homedir-relative) path + FILENAME a bind mount to the corresponding path in the per-application directory, + allowing that location to be used for persistent data. + This updates the [Context] group in the metadata. + This option can be used multiple times. +
--no-exports: + Don't look for exports in the build. +
-v, --verbose: + Print debug information during command processing. +
--version: + Print version information and exit. +

Examples

+ $ flatpak build-finish /build/my-app --socket=x11 --share=ipc +

+Exporting share/applications/gnome-calculator.desktop
+Exporting share/dbus-1/services/org.gnome.Calculator.SearchProvider.service
+More than one executable
+Using gcalccmd as command
+Please review the exported files and the metadata
+

Name

flatpak-build-export — Create a repository from a build directory

Synopsis

flatpak build-export [OPTION...] LOCATION DIRECTORY [BRANCH]

Description

+ Creates or updates a repository with an application build. + LOCATION is the location of the + repository. DIRECTORY must be a + finalized build directory. If BRANCH + is not specified, it is assumed to be "master". +

+ If LOCATION exists, it is assumed to + be an OSTree repository, otherwise a new OSTree repository is + created at this location. The repository can be inspected with + the ostree tool. +

+ The contents of DIRECTORY are committed + on the branch with name app/APPNAME/ARCH/BRANCH, + where ARCH is the architecture of the runtime that the application + is using. A commit filter is used to enforce that only the contents + of the files/ and export/ + subdirectories and the metadata file are included + in the commit, anything else is ignored. +

+ The repo-update command should be used to update repository + metadata whenever application builds are added to a repository. +

Options

The following options are understood:

-h, --help: + Show help options and exit. +
-s, --subject=SUBJECT: + One line subject for the commit message. +
-b, --body=BODY: + Full description for the commit message. +
--arch=ARCH: + Specify the architecture component of the branch to export. Only host compatible architectures can be specified. +
--exclude=PATTERN: + Exclude files matching PATTERN from the commit. +
--include=PATTERN: + Don't exclude files matching PATTERN from the commit, even if they match the --export patterns. +
--metadata=FILENAME: + Use the specified filename as metadata in the exported app instead of + the default file (called metadata). This is useful + if you want to commit multiple things from a single build tree, typically + used in combination with --files and --exclude. +
--files=SUBDIR: + Use the files in the specified subdirectory as the file contents, rather + than the regular files directory. +
--update-appstream: + Run appstream-builder and to update the appstream branch after build. +
--gpg-sign=KEYID: + Sign the commit with this GPG key +
--gpg-homedir=PATH: + GPG Homedir to use when looking for keyrings +
--runtime: + Export a runtime instead for an app (this uses the usr subdir as files). +
-v, --verbose: + Print debug information during command processing. +
--version: + Print version information and exit. +

Examples

+ $ flatpak build-export ~/repos/gnome-calculator/ ~/build/gnome-calculator/ org.gnome.Calculator +

+Commit: 9d0044ea480297114d03aec85c3d7ae3779438f9d2cb69d717fb54237acacb8c
+Metadata Total: 605
+Metadata Written: 5
+Content Total: 1174
+Content Written: 1
+Content Bytes Written: 305
+

Name

flatpak-build-bundle — Create a single-file bundle from a local repository

Synopsis

flatpak build-bundle [OPTION...] LOCATION FILENAME NAME [BRANCH]

Description

+ Creates a single-file named FILENAME + for the application (or runtime) named NAME + in the repository at LOCATION . If + a BRANCH is specified, this branch of + the application is used. +

+ The format of the bundle file is that of an ostree static delta + (against an empty base) with some flatpak specific metadata for + the application icons and appdata. +

Options

The following options are understood:

-h, --help: + Show help options and exit. +
--runtime: + Export a runtime instead of an application. +
--arch=ARCH: + The arch to create a bundle for. +
--repo-url=URL: + The URL for the repository from which the + application can be updated. Installing the + bundle will automatically configure a remote + for this URL. +
--gpg-keys=FILE: + Add the GPG key from FILE (use - for stdin). +
--gpg-homedir=PATH: + GPG Homedir to use when looking for keyrings. +
--oci: + Export to an OCI image instead of a Flatpak bundle. +
-v, --verbose: + Print debug information during command processing. +
--version: + Print version information and exit. +

Name

flatpak-build-import-bundle — Import a file bundle into a local repository

Synopsis

flatpak build-import-bundle [OPTION...] LOCATION FILENAME

Description

+ Imports a bundle from a file named FILENAME + into the repository at LOCATION . +

+ The format of the bundle file is that generated by build-bundle. +

Options

The following options are understood:

-h, --help: + Show help options and exit. +
-v, --verbose: + Print debug information during command processing. +
--ref=REF: + Override the ref specified in the bundle. +
--oci: + Import an OCI image instead of a Flatpak bundle. +
--version: + Print version information and exit. +

Name

flatpak-build-update-repo — Create a repository from a build directory

Synopsis

flatpak build-update-repo [OPTION...] LOCATION

Description

+ Updates repository metadata for the repository at + LOCATION . This command generates + an OSTree summary file that lists the contents of the repository. + The summary is used by flatpak repo-contents and other commands + to display the contents of remote repositories. +

+ After this command, LOCATION can be + used as the repository location for flatpak add-repo, either by + exporting it over http, or directly with a file: url. +

Options

The following options are understood:

-h, --help: + Show help options and exit. +
--title=TITLE: + A title for the repository, e.g. for display in a UI. + The title is stored in the repository summary. +
--gpg-sign=KEYID: + Sign the commit with this GPG key +
--gpg-homedir=PATH: + GPG Homedir to use when looking for keyrings +
--generate-static-deltas: + Generate static deltas for all references. This generates from-empty and + delta static files that allow for faster download. +
--prune: + Remove unreferences objects in repo. +
--prune-depth: + Only keep at most this number of old versions for any particular ref. Default is -1 which means infinite. +
-v, --verbose: + Print debug information during command processing. +
--version: + Print version information and exit. +

Name

flatpak-build-sign — Sign an application or runtime

Synopsis

flatpak build-sign [OPTION...] LOCATION ID [BRANCH]

Description

+ Signs the commit for a specified application or runtime in + a local repository. LOCATION is + the location of the repository. ID is the name of the application, or + runtime if --runtime is specified. If BRANCH is not specified, it is + assumed to be "master". +

+ Applications can also be signed during build-export, but + it is sometimes useful to add additional signatures later. +

Options

The following options are understood:

-h, --help: + Show help options and exit. +
--gpg-sign=KEYID: + Sign the commit with this GPG key +
--gpg-homedir=PATH: + GPG Homedir to use when looking for keyrings +
--runtime: + Sign a runtime instead of an app. +
--arch=ARCH: + The architecture to use. +
-v, --verbose: + Print debug information during command processing. +
--version: + Print version information and exit. +

Examples

+ $ flatpak build-export ~/repos/gnome-calculator/ ~/build/gnome-calculator/ org.gnome.Calculator +

+Commit: 9d0044ea480297114d03aec85c3d7ae3779438f9d2cb69d717fb54237acacb8c
+Metadata Total: 605
+Metadata Written: 5
+Content Total: 1174
+Content Written: 1
+Content Bytes Written: 305
+

Name

flatpak-builder — Help build application dependencies

Synopsis

flatpak-builder [OPTION...] DIRECTORY MANIFEST

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

Description

+ flatpak-builder is a wrapper around the flatpak build command + that automates the building of applications and their dependencies. It is one option you can use + to build applications. +

+ The goal of flatpak-builder is to push as much knowledge about how to build modules to + the individual upstream projects. It does this by assuming that the modules adhere to the Build API specified + at https://github.com/cgwalters/build-api. This essentially means that it follows the ./configure + && make && make install scheme with an optional autogen script. If the upstream + does not adhere to the API you can make it do so by adding patches and extra files. +

+ An invocation of flatpak-builder proceeds in these stages, each being 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

+ + After this you will end up with a build of the application in DIRECTORY , which you can + export to a repository with the flatpak build-export command. If you use the --repo + option, flatpack-builder will do the export for you at the end of the build process. When flatpak-builder does the + export, it also stores the manifest that was used for the build in /app/manifest.json. The manifest is 'resolved', + i.e. git branch names are replaced by the actual commit IDs that were used in the build. +

+ At each of the above steps flatpak caches the result, and if you build the same file again, it will start + of at the first step where something changes. For instance the first version controlled source that had + new commits added, or the first module where some changes to the MANIFEST file caused + the build environment to change. This makes flatpak-builder very efficient for incremental builds. +

Manifest format

Toplevel

+ The top level of the json file describes global + attributes of the application, and how it can be + build, and the list of modules that need to be + built. +

+ These are the properties that are accepted: +

id or app-id (string): A string defining the application id.
branch (string): The branch of the application, defaults to master.
runtime (string): The name of the runtime that the application uses.
runtime-version (string): The version of the runtime that the application uses, defaults to master.
sdk (string): The name of the development runtime that the application builds with.
var (string): Initialize the (otherwise empty) writable /var in the build with a copy of this runtime.
metadata (string): Use this file as the base metadata file when finishing.
command (string): The filename or path to the main binary of the application. Note that this is really just a single file, not a commandline. If you want to pass arguments, install a shell script wrapper and use that as the command.
build-runtime (boolean): Build a new runtime instead of an application.
separate-locales (boolean): Separate out locale files and translations to an extension runtime. Defaults to true.
id-platform (string): When building a runtime sdk, also create a platform based on it with this id.
metadata-platform (string): The metadata file to use for the platform we create.
writable-sdk (boolean): If true, use a writable copy of the sdk for /usr. + Defaults to true if --build-runtime is specified.
appstream-compose (boolean): Run appstream-compose during cleanup phase. Defaults to true.
sdk-extensions (array of strings): Install these extra sdk extensions in /usr.
platform-extensions (array of strings): Install these extra sdk extensions when creating the platform.
tags (array of strings): Add these tags to the metadata file.
build-options (object): Object specifying the build environment. See below for details.
modules (array of objects or string): An array of object specifying the modules to be built in order. + String members in the array are interpreted as the name of a separate json file that contains a module. + See below for details.
cleanup (array of strings): An array of file patterns that should be removed at the end. + Patterns starting with / are taken to be full pathnames (without the /app prefix), otherwise they just match + the basename.
cleanup-commands (array of strings): An array of commandlines that are run during the cleanup phase.
cleanup-platform (array of strings): Extra files to clean up in the platform.
finish-args (array of strings): An array of arguments passed to the flatpak build-finish command.
rename-desktop-file (string): Any desktop file with this name will be renamed to a name based on id during the cleanup phase.
rename-appdata-file (string): Any appdata file with this name will be renamed to a name based on id during the cleanup phase.
rename-icon (string): Any icon with this name will be renamed to a name based on id during the cleanup phase.
copy-icon (boolean): If rename-icon is set, keep a copy of the old icon file.
desktop-file-name-prefix (string): This string will be prefixed to the Name key in the main application desktop file.
desktop-file-name-suffix (string): This string will be suffixed to the Name key in the main application desktop file.

Build Options

+ Build options specify the build environment of a module, and can be specified globally as + well as per-module. Options can also be specified on a per-architecture basis using the arch property. +

+ These are the properties that are accepted: +

cflags (string): This is set in the environment variable CFLAGS during the build.
cxxflags (string): This is set in the environment variable CXXFLAGS during the build.
prefix (string): The build prefix for the modules (defaults to /app for + applications and /usr for runtimes).
env (object): This is a dictionary defining environment variables to be set during the build.
build-args (array of strings): This is an array containing extra options to pass to flatpak build.
strip (boolean): If this is true (the default is false) then all ELF files will be stripped after install.
no-debuginfo (boolean): If this is true (the default is false) and strip is not set then all ELF files will have their debug info extracted to a separate file.
arch (object): This is a dictionary defining for each arch a separate build options object that override the main one.

Module

+ Each module specifies a source that has to be separately built and installed. It contains + the build options and a list of sources to download and extract before building. +

+ Modules can be nested, in order to turn related modules on and off with a single key. +

+ These are the properties that are accepted: +

name (string): The name of the module, used in e.g. build logs. The name is also used for constructing filenames and commandline arguments, therefore using spaces or '/' in this string is a bad idea.
disabled (boolean): If true, skip this module
sources (array of objects): An array of objects defining sources that will be downloaded and extracted in order
config-opts (array of strings): An array of options that will be passed to configure
make-args (array of strings): An array of arguments that will be passed to make
make-install-args (array of strings): An array of arguments that will be passed to make install
rm-configure (boolean): If true, remove the configure script before starting build
no-autogen (boolean): Ignore the existence of an autogen script
no-parallel-make (boolean): Don't call make with arguments to build in parallel
no-python-timestamp-fix (boolean): Don't fix up the *.py[oc] header timestamps for ostree use.
cmake (boolean): Use cmake instead of configure
builddir (boolean): Use a build directory that is separate from the source directory
subdir (string): Build inside this subdirectory of the extracted sources
build-options (object): A build options object that can override global options
post-install (array of strings): An array of shell command that are run after the install phase. Can for example + clean up the install dir, or install extra files. +
cleanup (array of strings): An array of file patterns that should be removed at the end. + Patterns starting with / are taken to be full pathnames (without the /app prefix), otherwise they just match + the basename. Note that any patterns will only match files installed by this module. +
cleanup-platform (array of strings): Extra files to clean up in the platform.
modules (array of objects or strings): An array of object specifying nested modules to be built before this one. + String members in the array are interpreted as names of a separate json file that contains a module.

Sources

+ These contain a pointer to the source that will be extracted into the source directory before + the build starts. They can be of several types, distinguished by the type property. +

Archive sources (tar, zip)

type: "archive"
path (string): The path of the archive
url (string): The url of a remote archive that will be downloaded. This overrides path if both are specified.
sha256 (string): The sha256 checksum of the file, verified after download
strip-components (integer): The number of initial pathname components to strip during extraction. Defaults to 1.
dest (string): Directory inside the source dir where the archive will be extracted.

Git sources

type: "git"
url (string): URL of the git repository
branch (string): The branch/tag/commit to use from the git repository
dest (string): Directory inside the source dir where the repository will be checked out.

Bzr sources

type: "bzr"
url (string): URL of the bzr repository
revision (string): A specific revision to use in the branch
dest (string): Directory inside the source dir where the repository will be checked out.

File sources

type: "file"
path (string): The path of a local file that will be copied into the source dir
url (string): The url of a remote file that will be downloaded and copied into the source dir. This overrides path if both are specified.
sha256 (string): The sha256 checksum of the file, verified after download. This is optional for local files.
dest-filename (string): Filename to use inside the source dir, default to the basename of path.
dest (string): Directory inside the source dir where the file will be copied.

Script sources

+ This is a way to create a shell (/bin/sh) script from an inline set of commands. +

type: "script"
commands (array of strings): An array of shell commands that will be put in a shellscript file
dest-filename (string): Filename to use inside the source dir, default to the basename of path.
dest (string): Directory inside the source dir where the file will be copied.

Shell sources

+ This is a to create/modify the sources by running shell commands. +

type: "shell"
commands (array of strings): An array of shell commands that will be run during source extraction

Patch sources

type: "patch"
path (string): The path of a patch file that will be applied in the source dir
strip-components (integer): The value of the -p argument to patch, defaults to 1.
dest (string): Directory inside the source dir where the patch will be applied.
use-git (boolean): Whether to use "git apply" rather than "patch" to apply the patch, required when the patch file contains binary diffs.

Options

The following options are understood:

-h, --help: + Show help options and exit. +
-v, --verbose: + Print debug information during command processing. +
--version: + Print version information and exit. +
--arch=ARCH: + Specify the machine architecture to build for. If no architecture is specified, the host architecture will be automatically detected. Only host compatible architectures can be specified. +
--disable-cache: + Don't look at the existing cache for a previous build, instead always rebuild modules. +
--disable-download: + Don't download any sources. This only works if some version of all sources are downloaded + already. This is useful if you want to guarantee that no network i/o is done. However, the + build will fail if some source is not locally available. +
--disable-updates: + Download missing sources, but don't update local mirrors of version control repos. This is useful + to rebuild things but without updating git or bzr repositories from the remote repository. +
--run: + Run a command in a sandbox based on the build dir. This starts flatpak build, with some extra + arguments to give the same environment as the build, and the same permissions the final app + will have. The command to run must be the last argument passed to + flatpak-builder, after the directory and the manifest. +
--download-only: + Exit successfully after downloading the required sources. +
--build-only: + Don't do the cleanup and finish stages, which is useful if you + want to build more things into the app. +
--require-changes: + Do nothing, leaving a non-existent DIRECTORY if nothing changes since + last cached build. If this is not specified, the latest version from the cache will be put + into DIRECTORY . +
--keep-build-dirs: + Don'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"). +
--ccache: + Enable use of ccache in the build (needs ccache in the sdk) +
--repo=DIR: + When build is done, run export the result to this repository. +
-s, --subject=SUBJECT: + One line subject for the commit message. + Used when exporting the build results. +
-b, --body=BODY: + Full description for the commit message. + Used when exporting the build results. +
--gpg-sign=KEYID: + Sign the commit with this GPG key. + Used when exporting the build results. +
--gpg-homedir=PATH: + GPG Homedir to use when looking for keyrings. + Used when exporting the build results. +
--force-clean: + Erase the previous contents of DIRECTORY if it is + not empty. +

Caching

+ flatpak-builder caches sources and partial build results in + the .flatpak-builder subdirectory of the current directory. If you + use --keep-build-dirs, build directories for each + module are also stored here. +

+ It is safe to remove the contents of the .flatpak-builder + directory. This will force a full build the next time you build. +

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",
+    "clean": [ "/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": "git://git.gnome.org/babl"
+                }
+            ]
+        },
+        {
+            "name": "testapp",
+            "sources": [
+                {
+                    "type": "bzr",
+                    "url": "lp:testapp"
+                }
+            ]
+        }
+    ]
+}
+

Name

flatpak-metadata — Information about an application or runtime

Description

+ Flatpak uses metadata files to describe applications and runtimes. + The metadata file for a deployed application or + runtime is placed in the toplevel deploy directory. For example, the + metadata for the locally installed application org.gnome.Calculator + is in + ~/.local/share/flatpak/app/org.gnome.Calculator/current/active/metadata. +

+ Most aspects of the metadata configuration can be overridden when + launching applications, either temporarily via options of the flatpak + run command, or permanently with the flatpak override command. +

+ A metadata file describing the effective configuration is available + inside the running sandbox at /run/user/$UID/flatpak-info. +

File format

+ The metadata file is using the same .ini file format that is used for + systemd unit files or application .desktop files. +

[Application] or [Runtime]

+ Metadata for applications starts with an [Application] group, + metadata for runtimes with a [Runtime] group. +

+ The following keys can be present in these groups: +

name (string): The name of the application or runtime. This key is mandatory.
runtime (string): The fully qualified name of the runtime that is used by the application. This key is mandatory for applications.
sdk (string): The fully qualified name of the sdk that matches the runtime.
command (string): The command to run. Only relevant for applications.

[Context]

+ This group determines various system resources that may be shared + with the application when it is run in a flatpak sandbox. +

+ All keys in this group (and the group itself) are optional. +

shared (list): + List of subsystems to share with the host system. + Possible subsystems: network, ipc. +
sockets (list): + List of well-known sockets to make available in the sandbox. + Possible sockets: x11, wayland, pulseaudio, session-bus, system-bus. + When making a socket available, flatpak also sets + well-known environment variables like DISPLAY or + DBUS_SYSTEM_BUS_ADDRESS to let the application + find sockets that are not in a fixed location. +
devices (list): + List of devices to make available in the sandbox. + Possible values: dri, all. +
filesystems (list): + List of filesystem subsets to make available to the + application. Possible values: home, host, xdg-desktop, + xdg-documents, xdg-download xdg-music, xdg-pictures, + xdg-public-share, xdg-templates, xdg-videos, xdg-run, + an absolute path, or a homedir-relative path like + ~/dir or paths relative to the xdg dirs, like + xdg-download/subdir. The xdg-* arguments can also + specify a subdirectory, such as xdg-pictures/screenshots. + Each entry can have a suffix of + :ro or :rw to indicate if the path should be shared + read-only or read-write (default is read-write). +
persistent (list): + List of homedir-relative paths to make available at + the corresponding path in the per-application home directory, + allowing the locations to be used for persistent data when + the application does not have access to the real homedir. + For instance making ".myapp" persistent would make "~/.myapp" + in the sandbox a bind mount to "~/.var/app/org.my.App/.myapp", + thus allowing an unmodified application to save data in + the per-application location. +

[Session Bus Policy]

+ If the sockets key is not allowing full access + to the D-Bus session bus, then flatpak provides filtered access. +

+ The default policy for the session bus only allows the + application to own its own application ID and + subnames. For instance if the app is called + "org.my.App", it can only own "org.my.App" and + "org.my.App.*". Its also only allowed to talk to the + bus itself (org.freedesktop.DBus) and the portal APIs + APIs (bus names of the form org.freedesktop.portal.*). +

+ Additionally the app is always allowed to reply to + messages sent to it, and emit broadcast signals (but + these will not reach other sandboxed apps unless they + are allowed to talk to your app. +

+ If the [Session Bus Policy] group is present, it provides + policy for session bus access. +

+ Each key in this group has the form of a D-Bus bus name or + prefix thereof, for example org.gnome.SessionManager + or org.freedesktop.portal.* +

+ The possible values for entry are, in increasing order or + access: +

none: + The bus name or names in question is invisible to the application. +
see: + The bus name or names can be enumerated by the application. +
talk: + The application can send messages/ and receive replies and signals from the bus name or names. +
own: + The application can own the bus name or names (as well as all the above). +

[System Bus Policy]

+ If the sockets key is not allowing full access + to the D-Bus system bus, then flatpak does not make the system + bus available unless the [System Bus Policy] group is present + and provides a policy for filtered access. +

+ Entries in this group have the same form as for the [Session Bus Policy] group. + However, the app has no permissions by default. +

[Environment]

+ The [Environment] group specifies environment variables to set + when running the application. +

+ Entries in this group have the form VAR=VALUE + where VAR is the name of an environment variable + to set. +

[Extension NAME]

+ Runtimes and applications can define extensions, which are optional, + additional runtimes to be mounted at a specified location inside + the sandbox when they are present on the system. Typical uses for + extensions include translations for applications, or debuginfo + for sdks. The name of the extension is specified as part of the + group heading. +

directory (string): + The relative path at which the extension will be mounted in + the sandbox. If the extension is for an application, the + path is relative to /app, otherwise + it is relative to /usr. This key + is mandatory. +
version (string): + The branch to use when looking for the extension. If this is + not specified, it defaults to the branch of the application or + runtime that the extension is for. +
subdirectories (boolean): + If this key is set to true, then flatpak will look for + extensions whose name is a prefix of the extension name, and + mount them at the corresponding name below the subdirectory. +
no-autodownload (boolean): + Whether to automatically download this extension + when updating or installing a 'related' application + or runtime. +
autodelete (boolean): + Whether to automatically delete this extension + when deleting a 'related' application or runtime. +

Example

+[Application]
+name=org.gnome.Calculator
+runtime=org.gnome.Platform/x86_64/3.20
+sdk=org.gnome.Sdk/x86_64/3.20
+command=gnome-calculator
+
+[Context]
+shared=network;ipc;
+sockets=x11;wayland;
+filesystems=xdg-run/dconf;~/.config/dconf:ro;
+
+[Session Bus Policy]
+ca.desrt.dconf=talk
+
+[Environment]
+DCONF_USER_CONFIG_DIR=.config/dconf
+
+[Extension org.gnome.Calculator.Locale]
+directory=share/runtime/locale
+subdirectories=true
+
+[Extension org.gnome.Calculator.Debug]
+directory=lib/debug
+

Name

flatpak-make-current — Make a specific version of an app current

Synopsis

flatpak make-current [OPTION...] APP BRANCH

Description

+ Makes a particular branch of an application current. Only the current branch + of an app has its exported files (such as desktop files and icons) made visible + to the host. +

+ When a new branch is installed it will automatically be made current, so this + command is often not needed. +

+ Unless overridden with the --user option, this command creates a + system-wide installation. +

Options

The following options are understood:

-h, --help: + Show help options and exit. +
--user: + Create a per-user installation. +
--system: + Create a system-wide installation. +
--arch=ARCH: + The architecture to install for. +
-v, --verbose: + Print debug information during command processing. +
--version: + Print version information and exit. +

Examples

+ $ flatpak --user make-current org.gnome.GEdit 3.14 +

FlatpakInstallation

FlatpakInstallation — Installation information

Functions

++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+FlatpakInstallation * +	+flatpak_installation_new_system () +
+FlatpakInstallation * +	+flatpak_installation_new_user () +
+FlatpakInstallation * +	+flatpak_installation_new_for_path () +
+gboolean +	+flatpak_installation_get_is_user () +
+GFile * +	+flatpak_installation_get_path () +
+GFileMonitor * +	+flatpak_installation_create_monitor () +
+FlatpakInstalledRef * +	+flatpak_installation_install () +
+FlatpakInstalledRef * +	+flatpak_installation_update () +
+gboolean +	+flatpak_installation_uninstall () +
+gboolean +	+flatpak_installation_launch () +
+FlatpakInstalledRef * +	+flatpak_installation_get_current_installed_app () +
+FlatpakInstalledRef * +	+flatpak_installation_get_installed_ref () +
+GPtrArray * +	+flatpak_installation_list_installed_refs () +
+GPtrArray * +	+flatpak_installation_list_installed_refs_by_kind () +
+GPtrArray * +	+flatpak_installation_list_installed_refs_for_update () +
+GPtrArray * +	+flatpak_installation_list_remote_refs_sync () +
+GPtrArray * +	+flatpak_installation_list_remotes () +
+FlatpakRemote * +	+flatpak_installation_get_remote_by_name () +
+GBytes * +	+flatpak_installation_fetch_remote_metadata_sync () +
+FlatpakRemoteRef * +	+flatpak_installation_fetch_remote_ref_sync () +
+gboolean +	+flatpak_installation_fetch_remote_size_sync () +
+char * +	+flatpak_installation_load_app_overrides () +
+gboolean +	+flatpak_installation_update_appstream_sync () +
+FlatpakInstalledRef * +	+flatpak_installation_install_bundle () +
+gboolean +	+flatpak_installation_drop_caches () +
+gboolean +	+flatpak_installation_modify_remote () +
+gboolean +	+flatpak_installation_remove_remote () +
const char * +	+flatpak_get_default_arch () +
+void +	+(*FlatpakProgressCallback) () +

Types and Values

++++ + + + + + + + + + + +

struct	FlatpakInstallation
enum	FlatpakUpdateFlags

Object Hierarchy

    GObject
+    ╰── FlatpakInstallation
+

Description

FlatpakInstallation is the toplevel object that software installers +should use to operate on an flatpak applications.

An FlatpakInstallation object provides information about an installation +location for flatpak applications. Typical installation locations are either +system-wide (in /var/lib/flatpak) or per-user (in ~/.local/share/flatpak).

FlatpakInstallation can list configured remotes as well as installed application +and runtime references (in short: refs). It can also run, install, update and +uninstall applications and runtimes.

Functions

flatpak_installation_new_system ()

FlatpakInstallation *
+flatpak_installation_new_system (GCancellable *cancellable,
+                                 GError **error);

Creates a new FlatpakInstallation for the system-wide installation.

Parameters

+++++ + + + + + + + + + + + + +

cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

a new FlatpakInstallation.

[transfer full]

flatpak_installation_new_user ()

FlatpakInstallation *
+flatpak_installation_new_user (GCancellable *cancellable,
+                               GError **error);

Creates a new FlatpakInstallation for the per-user installation.

Parameters

+++++ + + + + + + + + + + + + +

cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

a new FlatpakInstallation.

[transfer full]

flatpak_installation_new_for_path ()

FlatpakInstallation *
+flatpak_installation_new_for_path (GFile *path,
+                                   gboolean user,
+                                   GCancellable *cancellable,
+                                   GError **error);

Creates a new FlatpakInstallation for the installation at the given path +.

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + +

path	a GFile
user	whether this is a user-specific location
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

a new FlatpakInstallation.

[transfer full]

flatpak_installation_get_is_user ()

gboolean
+flatpak_installation_get_is_user (FlatpakInstallation *self);

Returns whether the installation is for a user-specific location.

Parameters

+++++ + + + + + +

self

a FlatpakInstallation

Returns

TRUE if self +is a per-user installation

flatpak_installation_get_path ()

GFile *
+flatpak_installation_get_path (FlatpakInstallation *self);

Returns the installation location for self +.

Parameters

+++++ + + + + + +

self

a FlatpakInstallation

Returns

an GFile.

[transfer full]

flatpak_installation_create_monitor ()

GFileMonitor *
+flatpak_installation_create_monitor (FlatpakInstallation *self,
+                                     GCancellable *cancellable,
+                                     GError **error);

Gets monitor object for the installation. The returned file monitor will +emit the “changed” signal whenever an application or runtime +was installed, uninstalled or updated.

Parameters

+++++ + + + + + + + + + + + + + + + + + +

self	a FlatpakInstallation
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

a new GFileMonitor instance, or NULL on error.

[transfer full]

flatpak_installation_install ()

FlatpakInstalledRef *
+flatpak_installation_install (FlatpakInstallation *self,
+                              const char *remote_name,
+                              FlatpakRefKind kind,
+                              const char *name,
+                              const char *arch,
+                              const char *branch,
+                              FlatpakProgressCallback progress,
+                              gpointer progress_data,
+                              GCancellable *cancellable,
+                              GError **error);

Install a new application or runtime.

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self	a FlatpakInstallation
remote_name	name of the remote to use
kind	what this ref contains (an FlatpakRefKind)
name	name of the app/runtime to fetch
arch	which architecture to fetch (default: current architecture).	[nullable]
branch	which branch to fetch (default: 'master').	[nullable]
progress	progress callback.	[scope call]
progress_data	user data passed to `progress` +
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

The ref for the newly installed app or NULL on failure.

[transfer full]

flatpak_installation_update ()

FlatpakInstalledRef *
+flatpak_installation_update (FlatpakInstallation *self,
+                             FlatpakUpdateFlags flags,
+                             FlatpakRefKind kind,
+                             const char *name,
+                             const char *arch,
+                             const char *branch,
+                             FlatpakProgressCallback progress,
+                             gpointer progress_data,
+                             GCancellable *cancellable,
+                             GError **error);

Update an application or runtime.

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self	a FlatpakInstallation
flags	set of FlatpakUpdateFlags flag
kind	whether this is an app or runtime
name	name of the app or runtime to update
arch	architecture of the app or runtime to update (default: current architecture).	[nullable]
branch	name of the branch of the app or runtime to update (default: master).	[nullable]
progress	the callback.	[scope call]
progress_data	user data passed to `progress` +
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

The ref for the newly updated app (or the same if no update) or NULL on failure.

[transfer full]

flatpak_installation_uninstall ()

gboolean
+flatpak_installation_uninstall (FlatpakInstallation *self,
+                                FlatpakRefKind kind,
+                                const char *name,
+                                const char *arch,
+                                const char *branch,
+                                FlatpakProgressCallback progress,
+                                gpointer progress_data,
+                                GCancellable *cancellable,
+                                GError **error);

Uninstall an application or runtime.

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self	a FlatpakInstallation
kind	what this ref contains (an FlatpakRefKind)
name	name of the app or runtime to uninstall
arch	architecture of the app or runtime to uninstall
branch	name of the branch of the app or runtime to uninstall
progress	the callback.	[scope call]
progress_data	user data passed to `progress` +
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

TRUE on success

flatpak_installation_launch ()

gboolean
+flatpak_installation_launch (FlatpakInstallation *self,
+                             const char *name,
+                             const char *arch,
+                             const char *branch,
+                             const char *commit,
+                             GCancellable *cancellable,
+                             GError **error);

Launch an installed application.

You can use flatpak_installation_get_installed_ref() or +flatpak_installation_get_current_installed_app() to find out what builds +are available, in order to get a value for commit +.

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self	a FlatpakInstallation
name	name of the app to launch
arch	which architecture to launch (default: current architecture).	[nullable]
branch	which branch of the application (default: "master").	[nullable]
commit	the commit of `branch` +to launch.	[nullable]
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

TRUE, unless an error occurred

flatpak_installation_get_current_installed_app ()

FlatpakInstalledRef *
+flatpak_installation_get_current_installed_app
+                               (FlatpakInstallation *self,
+                                const char *name,
+                                GCancellable *cancellable,
+                                GError **error);

Get the last build of reference name + that was installed with +flatpak_installation_install(), or NULL if the reference has +never been installed locally.

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + +

self	a FlatpakInstallation
name	the name of the app
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

an FlatpakInstalledRef.

[transfer full]

flatpak_installation_get_installed_ref ()

FlatpakInstalledRef *
+flatpak_installation_get_installed_ref
+                               (FlatpakInstallation *self,
+                                FlatpakRefKind kind,
+                                const char *name,
+                                const char *arch,
+                                const char *branch,
+                                GCancellable *cancellable,
+                                GError **error);

Returns information about an installed ref, such as the available builds, +its size, location, etc.

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self	a FlatpakInstallation
kind	whether this is an app or runtime
name	name of the app/runtime to fetch
arch	which architecture to fetch (default: current architecture).	[nullable]
branch	which branch to fetch (default: "master").	[nullable]
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

an FlatpakInstalledRef, or NULL if an error occurred.

[transfer full]

flatpak_installation_list_installed_refs ()

GPtrArray *
+flatpak_installation_list_installed_refs
+                               (FlatpakInstallation *self,
+                                GCancellable *cancellable,
+                                GError **error);

Lists the installed references.

Parameters

+++++ + + + + + + + + + + + + + + + + + +

self	a FlatpakInstallation
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

an GPtrArray of +FlatpakInstalledRef instances.

[transfer container][element-type FlatpakInstalledRef]

flatpak_installation_list_installed_refs_by_kind ()

GPtrArray *
+flatpak_installation_list_installed_refs_by_kind
+                               (FlatpakInstallation *self,
+                                FlatpakRefKind kind,
+                                GCancellable *cancellable,
+                                GError **error);

Lists the installed references of a specific kind.

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + +

self	a FlatpakInstallation
kind	the kind of installation
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

an GPtrArray of +FlatpakInstalledRef instances.

[transfer container][element-type FlatpakInstalledRef]

flatpak_installation_list_installed_refs_for_update ()

GPtrArray *
+flatpak_installation_list_installed_refs_for_update
+                               (FlatpakInstallation *self,
+                                GCancellable *cancellable,
+                                GError **error);

Lists the installed references that has a remote update that is not +locally available. However, even though an app is not returned by this +it can have local updates available that has not been deployed. Look +at commit vs latest_commit on installed apps for this.

Parameters

+++++ + + + + + + + + + + + + + + + + + +

self	a FlatpakInstallation
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

an GPtrArray of +FlatpakInstalledRef instances.

[transfer container][element-type FlatpakInstalledRef]

flatpak_installation_list_remote_refs_sync ()

GPtrArray *
+flatpak_installation_list_remote_refs_sync
+                               (FlatpakInstallation *self,
+                                const char *remote_name,
+                                GCancellable *cancellable,
+                                GError **error);

Lists all the applications and runtimes in a remote.

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + +

self	a FlatpakInstallation
remote_name	the name of the remote
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

an GPtrArray of +FlatpakRemoteRef instances.

[transfer container][element-type FlatpakRemoteRef]

flatpak_installation_list_remotes ()

GPtrArray *
+flatpak_installation_list_remotes (FlatpakInstallation *self,
+                                   GCancellable *cancellable,
+                                   GError **error);

Lists the remotes, in priority (highest first) order. For same priority, +an earlier added remote comes before a later added one.

Parameters

+++++ + + + + + + + + + + + + + + + + + +

self	a FlatpakInstallation
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

an GPtrArray of +FlatpakRemote instances.

[transfer container][element-type FlatpakRemote]

flatpak_installation_get_remote_by_name ()

FlatpakRemote *
+flatpak_installation_get_remote_by_name
+                               (FlatpakInstallation *self,
+                                const gchar *name,
+                                GCancellable *cancellable,
+                                GError **error);

Looks up a remote by name.

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + +

self	a FlatpakInstallation
name	a remote name
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

a FlatpakRemote instances, or NULL error.

[transfer full]

flatpak_installation_fetch_remote_metadata_sync ()

GBytes *
+flatpak_installation_fetch_remote_metadata_sync
+                               (FlatpakInstallation *self,
+                                const char *remote_name,
+                                FlatpakRef *ref,
+                                GCancellable *cancellable,
+                                GError **error);

Obtains the metadata file from a commit.

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self	a FlatpakInstallation
remote_name	the name of the remote
ref	the ref
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

a GBytes containing the flatpak metadata file, +or NULL if an error occurred.

[transfer full]

flatpak_installation_fetch_remote_ref_sync ()

FlatpakRemoteRef *
+flatpak_installation_fetch_remote_ref_sync
+                               (FlatpakInstallation *self,
+                                const char *remote_name,
+                                FlatpakRefKind kind,
+                                const char *name,
+                                const char *arch,
+                                const char *branch,
+                                GCancellable *cancellable,
+                                GError **error);

Gets the current remote branch of a ref in the remote.

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self	a FlatpakInstallation
remote_name	the name of the remote
kind	what this ref contains (an FlatpakRefKind)
name	name of the app/runtime to fetch
arch	which architecture to fetch (default: current architecture).	[nullable]
branch	which branch to fetch (default: 'master').	[nullable]
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

a FlatpakRemoteRef instance, or NULL.

[transfer full]

flatpak_installation_fetch_remote_size_sync ()

gboolean
+flatpak_installation_fetch_remote_size_sync
+                               (FlatpakInstallation *self,
+                                const char *remote_name,
+                                FlatpakRef *ref,
+                                guint64 *download_size,
+                                guint64 *installed_size,
+                                GCancellable *cancellable,
+                                GError **error);

Gets information about the maximum amount of data that needs to be transferred +to pull the ref from a remote repository, and about the amount of +local disk space that is required to check out this commit.

Note that if there are locally available data that are in the ref, which is common +for instance if you're doing an update then the real download size may be smaller +than what is returned here.

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self	a FlatpakInstallation
remote_name	the name of the remote
ref	the ref
download_size	return location for the (maximum) download size.	[out]
installed_size	return location for the installed size.	[out]
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

TRUE, unless an error occurred

flatpak_installation_load_app_overrides ()

char *
+flatpak_installation_load_app_overrides
+                               (FlatpakInstallation *self,
+                                const char *app_id,
+                                GCancellable *cancellable,
+                                GError **error);

Loads the metadata overrides file for an application.

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + +

self	a FlatpakInstallation
app_id	an application id
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

the contents of the overrides files, +or NULL if an error occurred.

[transfer full]

flatpak_installation_update_appstream_sync ()

gboolean
+flatpak_installation_update_appstream_sync
+                               (FlatpakInstallation *self,
+                                const char *remote_name,
+                                const char *arch,
+                                gboolean *out_changed,
+                                GCancellable *cancellable,
+                                GError **error);

Updates the local copy of appstream for remote_name + for the specified arch +.

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self	a FlatpakInstallation
remote_name	the name of the remote
arch	Architecture to update, or `NULL` for the local machine arch
out_changed	Set to `TRUE` if the contents of the appstream changed, `FALSE` if nothing changed.	[nullable]
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

TRUE on success, or FALSE on error

flatpak_installation_install_bundle ()

FlatpakInstalledRef *
+flatpak_installation_install_bundle (FlatpakInstallation *self,
+                                     GFile *file,
+                                     FlatpakProgressCallback progress,
+                                     gpointer progress_data,
+                                     GCancellable *cancellable,
+                                     GError **error);

Install an application or runtime from an flatpak bundle file. +See flatpak-build-bundle(1) for how to create brundles.

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

self	a FlatpakInstallation
file	a GFile that is an flatpak bundle
progress	progress callback.	[scope call]
progress_data	user data passed to `progress` +
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

The ref for the newly installed app or NULL on failure.

[transfer full]

flatpak_installation_drop_caches ()

gboolean
+flatpak_installation_drop_caches (FlatpakInstallation *self,
+                                  GCancellable *cancellable,
+                                  GError **error);

Drops all internal (in-memory) caches. For instance, this may be needed to pick up new or changed +remotes configured outside this installation instance.

Parameters

+++++ + + + + + + + + + + + + + + + + + +

self	a FlatpakInstallation
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

TRUE on success, FALSE on error

flatpak_installation_modify_remote ()

gboolean
+flatpak_installation_modify_remote (FlatpakInstallation *self,
+                                    FlatpakRemote *remote,
+                                    GCancellable *cancellable,
+                                    GError **error);

Saves changes in the remote + object.

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + +

self	a FlatpakInstallation
remote	the modified FlatpakRemote
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

TRUE if the modifications have been committed successfully

flatpak_installation_remove_remote ()

gboolean
+flatpak_installation_remove_remote (FlatpakInstallation *self,
+                                    const char *name,
+                                    GCancellable *cancellable,
+                                    GError **error);

Removes the remote with the given name from the installation.

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + +

self	a FlatpakInstallation
name	the name of the remote to remove
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

TRUE if the remote has been removed successfully

flatpak_get_default_arch ()

const char *
+flatpak_get_default_arch (void);

Returns the canonical name for the arch of the current machine.

Returns

an arch string

FlatpakProgressCallback ()

void
+(*FlatpakProgressCallback) (const char *status,
+                            guint progress,
+                            gboolean estimating,
+                            gpointer user_data);

The progress callback is called repeatedly during long-running operations +such as installations or updates, and can be used to update progress information +in a user interface.

The callback occurs in the thread-default context of the caller.

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + +

status	A status string, suitable for display
progress	percentage of completion
estimating	whether `progress` +is just an estimate
user_data	User data passed to the caller

Types and Values

struct FlatpakInstallation

struct FlatpakInstallation;

enum FlatpakUpdateFlags

Flags to alter the behavior of flatpak_installation_update().

Members

+++++ + + + + + + + + + + + + + + + + + +

FLATPAK_UPDATE_FLAGS_NONE	+ Fetch remote builds and install the latest one (default) +
FLATPAK_UPDATE_FLAGS_NO_DEPLOY	+ Don't install any new builds that might be fetched +
FLATPAK_UPDATE_FLAGS_NO_PULL	+ Don't try to fetch new builds from the remote repo +

const char * +	+flatpak_installed_ref_get_deploy_dir () +
+guint64 +	+flatpak_installed_ref_get_installed_size () +
+gboolean +	+flatpak_installed_ref_get_is_current () +
const char * +	+flatpak_installed_ref_get_latest_commit () +
const char * +	+flatpak_installed_ref_get_origin () +
+GBytes * +	+flatpak_installed_ref_load_metadata () +
const char * const * +	+flatpak_installed_ref_get_subpaths () +

+gchar *	deploy-dir	Read / Write
guint64	installed-size	Read / Write
gboolean	is-current	Read / Write
+gchar *	latest-commit	Read / Write
+gchar *	origin	Read / Write
GStrv	subpaths	Read / Write

+char * +	+flatpak_ref_format_ref () +
const char * +	+flatpak_ref_get_arch () +
const char * +	+flatpak_ref_get_branch () +
const char * +	+flatpak_ref_get_commit () +
+FlatpakRefKind +	+flatpak_ref_get_kind () +
const char * +	+flatpak_ref_get_name () +
+FlatpakRef * +	+flatpak_ref_parse () +

+gchar *	arch	Read / Write
+gchar *	branch	Read / Write
+gchar *	commit	Read / Write
FlatpakRefKind	kind	Read / Write
+gchar *	name	Read / Write

FLATPAK_REF_KIND_APP	+ An application +
FLATPAK_REF_KIND_RUNTIME	+ A runtime that applications can use. +

self	a FlatpakInstalledRef
cancellable	a GCancellable.	[nullable]
error	a return location for a GError

ref	A string ref name, such as "app/org.test.App/86_64/master"
error	return location for a GError

+FlatpakRemote * +	+flatpak_remote_new () +
const char * +	+flatpak_remote_get_name () +
+GFile * +	+flatpak_remote_get_appstream_dir () +
+GFile * +	+flatpak_remote_get_appstream_timestamp () +
+gboolean +	+flatpak_remote_get_gpg_verify () +
+void +	+flatpak_remote_set_gpg_verify () +
+void +	+flatpak_remote_set_gpg_key () +
+gboolean +	+flatpak_remote_get_noenumerate () +
+void +	+flatpak_remote_set_noenumerate () +
+int +	+flatpak_remote_get_prio () +
+void +	+flatpak_remote_set_prio () +
+char * +	+flatpak_remote_get_title () +
+void +	+flatpak_remote_set_title () +
+char * +	+flatpak_remote_get_url () +
+void +	+flatpak_remote_set_url () +
+gboolean +	+flatpak_remote_get_disabled () +
+void +	+flatpak_remote_set_disabled () +

self	a FlatpakRemote
arch	which architecture to fetch (default: current architecture).	[nullable]

FLATPAK_ERROR_ALREADY_INSTALLED	+ App/runtime is already installed +
FLATPAK_ERROR_NOT_INSTALLED	+ App/runtime is not installed +

#define	FLATPAK_MAJOR_VERSION
#define	FLATPAK_MINOR_VERSION
#define	FLATPAK_MICRO_VERSION
#define	FLATPAK_EXTERN

+FlatpakBundleRef * +	+flatpak_bundle_ref_new () +
+GFile * +	+flatpak_bundle_ref_get_file () +
+GBytes * +	+flatpak_bundle_ref_get_metadata () +
+GBytes * +	+flatpak_bundle_ref_get_appstream () +
+GBytes * +	+flatpak_bundle_ref_get_icon () +
+char * +	+flatpak_bundle_ref_get_origin () +
+guint64 +	+flatpak_bundle_ref_get_installed_size () +

Flatpak Command Reference

Name

Synopsis

Description

Options

Examples

See also

Name

Synopsis

Description

Options

Examples

See also

Name

Synopsis

Description

Options

Examples

Name

Synopsis

Description

Options

Examples

See also

Name

Synopsis

Description

Options

Examples

See also

Name

Synopsis

Description

Options

Examples

See also

Name

Synopsis

Description

Options

Examples

See also

Name

Synopsis

Description

Options

Examples

See also

Name

Synopsis

Description

Options

Examples

See also

Name

Synopsis

Description

Options

See also

Name

Synopsis

Description

Options

Examples

See also

Name

Synopsis

Description

Options

See also

Name

Synopsis

Description

Options

Examples

See also

Name

Synopsis

Description

Options