From 691f8137c48d57bb91ee23fabf793be8605d7e8e Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Wed, 1 Jul 2026 03:32:10 +0000 Subject: [PATCH 1/3] (Automated) Update Flatpak docs Update Flatpak docs from 1.17.0 to 1.18.0 --- docs/flatpak-docs.html | 418 ++++++++++++++++++++++++++++++++++++++--- 1 file changed, 391 insertions(+), 27 deletions(-) diff --git a/docs/flatpak-docs.html b/docs/flatpak-docs.html index a99258ca..74c03d01 100644 --- a/docs/flatpak-docs.html +++ b/docs/flatpak-docs.html @@ -1,5 +1,5 @@ -Flatpak Command Reference

Flatpak Command Reference

Version 1.17.0

Important

+Flatpak Command Reference

Flatpak Command Reference

Version 1.18.0

Important

The command reference is generated from the flatpak repo; see https://github.com/flatpak/flatpak/tree/main/doc

Flatpak comes with a rich commandline interface. @@ -276,11 +276,10 @@ time by --localstatedir or -Dsystem_install_dir).

FLATPAK_TTY_PROGRESS

- May be set to 1 to enable reporting + May be set to 0 to disable reporting machine-readable progress to the terminal. - This feature is not currently enabled by default - because it uses the OSC 9;4 sequence, - which some terminal emulators interpret as a + This feature can be disabled because it uses the OSC 9;4 + sequence, which some terminal emulators interpret as a popup notification.

FLATPAK_USER_DIR

The location of the per-user installation. If this is not set, @@ -329,6 +328,11 @@ The OSTree commit to create a delta bundle from.

--oci

Export to an OCI image instead of a Flatpak bundle. +

--oci-layer-compress=gzip|zstd

+ Choose how to compress the layers in OCI images. gzip (the + default) is universally supported, but zstd compresses faster + and results in smaller images. As of 2023, zstd support is + present in most major registries.

-v, --verbose

Print debug information during command processing.

--ostree-verbose

@@ -385,7 +389,7 @@ to be put in the named subset summary (in addition to the main one), allowing users to see only this subset instead of the whole repo.

--untrusted

- The source repostory is not trusted, all objects are copied (not hardlinked) and + The source repository is not trusted, all objects are copied (not hardlinked) and all checksums are verified.

-s, --subject=SUBJECT

One line subject for the commit message. If not specified, will be taken from the source commit. @@ -593,6 +597,23 @@ the [Context] group in the metadata. SUBSYSTEM must be one of: network, ipc. This option can be used multiple times. +

--share-if=SUBSYSTEM:CONDITION

+ Share a subsystem with the host session conditionally, + only when the specified condition is met at runtime. + This updates the [Context] group in the metadata. + SUBSYSTEM must be one of: network, ipc. + CONDITION must be one of: + true, false, + has-input-device, has-wayland, + has-usb-device, has-usb-portal. + Conditions can be negated with !, + for example !has-input-device. + This option can be used multiple times. + Available since 1.17. +

+ See the Conditional Permissions section in + flatpak-metadata(5) + for more details.

--socket=SOCKET

Expose a well-known socket to the application. This updates the [Context] group in the metadata. @@ -610,6 +631,21 @@ SOCKET must be one of: x11, wayland, fallback-x11, pulseaudio, system-bus, session-bus, ssh-auth, pcsc, cups, gpg-agent, inherit-wayland-socket. This option can be used multiple times. +

--socket-if=SOCKET:CONDITION

+ Expose a well-known socket to the application conditionally, + only when the specified condition is met at runtime. + This updates the [Context] group in the metadata. + SOCKET must be one of: x11, wayland, fallback-x11, pulseaudio, system-bus, session-bus, + ssh-auth, pcsc, cups, gpg-agent, inherit-wayland-socket. + CONDITION must be one of: true, false, has-input-device, has-wayland, has-usb-device, has-usb-portal. + Conditions can be negated with !, + for example !has-wayland. + This option can be used multiple times. + Available since 1.17. +

+ See the Conditional Permissions section in + flatpak-metadata(5) + for more details.

--device=DEVICE

Expose a device to the application. This updates the [Context] group in the metadata. @@ -620,6 +656,20 @@ the [Context] group in the metadata. DEVICE must be one of: dri, input, usb, kvm, shm, all. This option can be used multiple times. +

--device-if=DEVICE:CONDITION

+ Expose a device to the application conditionally, + only when the specified condition is met at runtime. + This updates the [Context] group in the metadata. + DEVICE must be one of: dri, input, usb, kvm, shm, all. + CONDITION must be one of: true, false, has-input-device, has-wayland, has-usb-device, has-usb-portal. + Conditions can be negated with !, + for example !has-input-device. + This option can be used multiple times. + Available since 1.17. +

+ See the Conditional Permissions section in + flatpak-metadata(5) + for more details.

--allow=FEATURE

Allow access to a specific feature. This updates the [Context] group in the metadata. @@ -656,6 +706,23 @@ FEATURE must be one of: devel, multiarch, bluetooth, canbus, per-app-dev-shm. This option can be used multiple times. +

--allow-if=FEATURE:CONDITION

+ Allow access to a specific feature conditionally, + only when the specified condition is met at runtime. + This updates the [Context] group in the metadata. + FEATURE must be one of: devel, multiarch, bluetooth. + CONDITION must be one of: + true, false, + has-input-device, has-wayland, + has-usb-device, has-usb-portal. + Conditions can be negated with !, + for example !has-input-device. + This option can be used multiple times. + Available since 1.17. +

+ See the Conditional Permissions section in + flatpak-metadata(5) + for more details.

--filesystem=FS

Allow the application access to a subset of the filesystem. This updates the [Context] group in the metadata. @@ -828,7 +895,12 @@ More than one executable Using gcalccmd as command Please review the exported files and the metadata -

See also

+

+ $ flatpak build-finish /build/my-app --socket=wayland --socket-if=x11:!has-wayland --share=ipc +

+ This grants Wayland access unconditionally and X11 access only when not running in a Wayland session, + allowing the application to fall back to X11 when needed. +

See also

flatpak(1), flatpak-build-init(1), flatpak-build(1), @@ -1130,6 +1202,7 @@ See the "[Context] filesystems" list in flatpak-metadata(5) for details of the meanings of these filesystems. + Before flatpak 1.17.0, access to host was granted by default.

--nofilesystem=FILESYSTEM

Remove access to the specified subset of the filesystem from the application. This overrides to the Context section from the @@ -1236,6 +1309,12 @@ (language, optional locale, optional codeset, optional modifier) as documented by setlocale(3) (for example, en;en_DK;zh_HK.big5hkscs;uz_UZ.utf8@cyrillic). +

report-os-info

+ If this key is set to false or the no-report-os-info + file exists at FLATPAK_CONFIG_DIR Flatpak will not report the OS name, + version, and architecture from /etc/os-release to the Flatpak + remote via the Flatpak-Os-Info HTTP header when pulling objects. + The default value of the key if unset is true.

For configuration of individual remotes, see flatpak-remote-modify(1). @@ -1647,7 +1726,7 @@

Name

flatpak-install — Install an application or runtime

Synopsis

flatpak install [OPTION...] [REMOTE] REF...

flatpak install [OPTION...] [--from|--bundle|--image] LOCATION

Description

Installs an application or runtime. The primary way to install is to specify a REMOTE - name as the source and one ore more REF s to specify the + name as the source and one or more REF s to specify the application or runtime to install. If REMOTE is omitted, the configured remotes are searched for the first REF and the user is asked to confirm the resulting choice. @@ -1677,6 +1756,14 @@ either with the --sideload-repo option, or on a per-installation or system-wide basis (see flatpak(1)). +

+ For OCI remotes, sideload repositories can also be specified as + --sideload-repo=oci:PATH or --sideload-repo=oci-archive:PATH, + where path points to an OCI image layout or archive of an OCI image layout. + (See containers-transports(5).) + When specified in this fashion, the images found in the image layout are available for all OCI remotes, + without regard to collection ID. For this reason, there is no directory equivalent - + it can only be specified on the command line.

The alternative form of the command (with --from, --bundle, or --image) allows to install directly from a source. The source can be a @@ -1973,6 +2060,23 @@ the Context section from the application metadata. SUBSYSTEM must be one of: network, ipc. This option can be used multiple times. +

--share-if=SUBSYSTEM:CONDITION

+ Share a subsystem with the host session conditionally, + only when the specified condition is met at runtime. + This overrides to the Context section from the application metadata. + SUBSYSTEM must be one of: network, ipc. + CONDITION must be one of: + true, false, + has-input-device, has-wayland, + has-usb-device, has-usb-portal. + Conditions can be negated with !, + for example !has-input-device. + This option can be used multiple times. + Available since 1.17. +

+ See the Conditional Permissions section in + flatpak-metadata(5) + for more details.

--socket=SOCKET

Expose a well-known socket to the application. This overrides to the Context section from the application metadata. @@ -1985,6 +2089,22 @@ SOCKET must be one of: x11, wayland, fallback-x11, pulseaudio, system-bus, session-bus, ssh-auth, pcsc, cups, gpg-agent, inherit-wayland-socket. This option can be used multiple times. +

--socket-if=SOCKET:CONDITION

+ Expose a well-known socket to the application conditionally, + only when the specified condition is met at runtime. + This overrides to the Context section from the application + metadata. + SOCKET must be one of: x11, wayland, fallback-x11, pulseaudio, system-bus, session-bus, + ssh-auth, pcsc, cups, gpg-agent, inherit-wayland-socket. + CONDITION must be one of: true, false, has-input-device, has-wayland, has-usb-device, has-usb-portal. + Conditions can be negated with !, + for example !has-wayland. + This option can be used multiple times. + Available since 1.17. +

+ See the Conditional Permissions section in + flatpak-metadata(5) + for more details.

--device=DEVICE

Expose a device to the application. This overrides to the Context section from the application metadata. @@ -1995,6 +2115,21 @@ the Context section from the application metadata. DEVICE must be one of: dri, input, usb, kvm, shm, all. This option can be used multiple times. +

--device-if=DEVICE:CONDITION

+ Expose a device to the application conditionally, + only when the specified condition is met at runtime. + This overrides to the Context section from the application + metadata. + DEVICE must be one of: dri, input, usb, kvm, shm, all. + CONDITION must be one of: true, false, has-input-device, has-wayland, has-usb-device, has-usb-portal. + Conditions can be negated with !, + for example !has-input-device. + This option can be used multiple times. + Available since 1.17. +

+ See the Conditional Permissions section in + flatpak-metadata(5) + for more details.

--allow=FEATURE

Allow access to a specific feature. This updates the [Context] group in the metadata. @@ -2012,6 +2147,23 @@ devel, multiarch, bluetooth, canbus, per-app-dev-shm. This option can be used multiple times. +

--allow-if=FEATURE:CONDITION

+ Allow access to a specific feature conditionally, + only when the specified condition is met at runtime. + This overrides to the Context section from the application metadata. + FEATURE must be one of: devel, multiarch, bluetooth. + CONDITION must be one of: + true, false, + has-input-device, has-wayland, + has-usb-device, has-usb-portal. + Conditions can be negated with !, + for example !has-input-device. + This option can be used multiple times. + Available since 1.17. +

+ See the Conditional Permissions section in + flatpak-metadata(5) + for more details.

--filesystem=FILESYSTEM

Allow the application access to a subset of the filesystem. This overrides to the Context section from the application metadata. @@ -2138,6 +2290,10 @@ $ flatpak override --nosocket=wayland org.gnome.gedit

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

+ $ flatpak override --socket-if=x11:!has-wayland org.example.App +

+ Grant X11 socket access only when not running in a Wayland session.

See also

flatpak(1), flatpak-run(1) @@ -2466,6 +2622,9 @@ 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. +

--signature-lookaside=URL

+ Specify an URL to be used to look up signatures for this + remote (OCI remotes only).

--authenticator-name=NAME

Specify the authenticator to use for the remote.

--authenticator-option=KEY=VALUE

@@ -2769,6 +2928,9 @@ 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. +

--signature-lookaside=URL

+ Specify an URL to be used to look up signatures for this + remote (OCI remotes only).

--authenticator-name=NAME

Specify the authenticator to use for the remote.

--authenticator-option=KEY=VALUE

@@ -2966,10 +3128,10 @@ arguments.

Environment variables are generally passed on to the sandboxed application, with - certain exceptions. The application metadata can override environment variables, - as well as the --env option. Apart from that, Flatpak always - unsets or overrides the following variables, since their session values - are likely to interfere with the functioning of the sandbox: + certain exceptions, if --clear-env is not specified. The application + metadata can override environment variables, as well as the --env + option. Apart from that, Flatpak always unsets or overrides the following variables, + since their session values are likely to interfere with the functioning of the sandbox:

PATH
LD_LIBRARY_PATH
LD_PRELOAD
LD_AUDIT
XDG_CONFIG_DIRS
XDG_DATA_DIRS
SHELL
TEMP
TEMPDIR
TMP
TMPDIR
XDG_RUNTIME_DIR
container
TZDIR
PYTHONPATH
PYTHONPYCACHEPREFIX
PERLLIB
PERL5LIB
XCURSOR_PATH
GST_PLUGIN_PATH_1_0
GST_REGISTRY
GST_REGISTRY_1_0
GST_PLUGIN_PATH
GST_PLUGIN_SYSTEM_PATH
GST_PLUGIN_SCANNER
GST_PLUGIN_SCANNER_1_0
GST_PLUGIN_SYSTEM_PATH_1_0
GST_PRESET_PATH
GST_PTP_HELPER
GST_PTP_HELPER_1_0
GST_INSTALL_PLUGINS_HELPER
KRB5CCNAME
XKB_CONFIG_ROOT
GIO_EXTRA_MODULES
GDK_BACKEND
VK_ADD_DRIVER_FILES
VK_ADD_LAYER_PATH
VK_DRIVER_FILES
VK_ICD_FILENAMES
VK_LAYER_PATH
__EGL_EXTERNAL_PLATFORM_CONFIG_DIRS
__EGL_EXTERNAL_PLATFORM_CONFIG_FILENAMES
__EGL_VENDOR_LIBRARY_DIRS
__EGL_VENDOR_LIBRARY_FILENAMES

Also several environment variables with the prefix "GST_" that are used by gstreamer are unset (since Flatpak 1.12.5). @@ -3043,6 +3205,23 @@ the Context section from the application metadata. SUBSYSTEM must be one of: network, ipc. This option can be used multiple times. +

--share-if=SUBSYSTEM:CONDITION

+ Share a subsystem with the host session conditionally, + only when the specified condition is met at runtime. + This overrides to the Context section from the application metadata. + SUBSYSTEM must be one of: network, ipc. + CONDITION must be one of: + true, false, + has-input-device, has-wayland, + has-usb-device, has-usb-portal. + Conditions can be negated with !, + for example !has-input-device. + This option can be used multiple times. + Available since 1.17. +

+ See the Conditional Permissions section in + flatpak-metadata(5) + for more details.

--socket=SOCKET

Expose a well known socket to the application. This overrides to the Context section from the application metadata. @@ -3055,16 +3234,51 @@ SOCKET must be one of: x11, wayland, fallback-x11, pulseaudio, system-bus, session-bus, ssh-auth, pcsc, cups, gpg-agent, inherit-wayland-socket. This option can be used multiple times. +

--socket-if=SOCKET:CONDITION

+ Expose a well-known socket to the application conditionally, + only when the specified condition is met at runtime. + This overrides to the Context section from the application metadata. + SOCKET must be one of: x11, wayland, fallback-x11, pulseaudio, system-bus, session-bus, + ssh-auth, pcsc, cups, gpg-agent, inherit-wayland-socket. + CONDITION must be one of: + true, false, + has-input-device, has-wayland, + has-usb-device, has-usb-portal. + Conditions can be negated with !, + for example !has-wayland. + This option can be used multiple times. + Available since 1.17. +

+ See the Conditional Permissions section in + flatpak-metadata(5) + for more details.

--device=DEVICE

Expose a device to the application. This overrides to the Context section from the application metadata. - DEVICE must be one of: dri, usb, input, kvm, shm, all. + DEVICE must be one of: dri, input, usb, kvm, shm, 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, usb, input, kvm, shm, all. + DEVICE must be one of: dri, input, usb, kvm, shm, all. + This option can be used multiple times. +

--device-if=DEVICE:CONDITION

+ Expose a device to the application conditionally, + only when the specified condition is met at runtime. + This overrides to the Context section from the application metadata. + DEVICE must be one of: dri, input, usb, kvm, shm, all. + CONDITION must be one of: + true, false, + has-input-device, has-wayland, + has-usb-device, has-usb-portal. + Conditions can be negated with !, + for example !has-input-device. This option can be used multiple times. + Available since 1.17. +

+ See the Conditional Permissions section in + flatpak-metadata(5) + for more details.

--allow=FEATURE

Allow access to a specific feature. This overrides to the Context section from the application metadata. @@ -3078,6 +3292,23 @@ the Context section from the application metadata. FEATURE must be one of: devel, multiarch, bluetooth. This option can be used multiple times. +

--allow-if=FEATURE:CONDITION

+ Allow access to a specific feature conditionally, + only when the specified condition is met at runtime. + This overrides to the Context section from the application metadata. + FEATURE must be one of: devel, multiarch, bluetooth. + CONDITION must be one of: + true, false, + has-input-device, has-wayland, + has-usb-device, has-usb-portal. + Conditions can be negated with !, + for example !has-input-device. + This option can be used multiple times. + Available since 1.17. +

+ See the Conditional Permissions section in + flatpak-metadata(5) + for more details.

--filesystem=FILESYSTEM

Allow the application access to a subset of the filesystem. This overrides to the Context section from the application metadata. @@ -3188,6 +3419,10 @@ followed by a zero byte. This is the same format used by env -0 and /proc/*/environ. +

--clear-env

+ Do not pass environment variables from the outside to the + sandboxed application. Explicitly set and unset environment + variables still get applied.

--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. @@ -3243,7 +3478,7 @@ Allow access to the accessibility bus. This is the default, except when run with --sandbox.

--sandbox

Run the application in sandboxed mode, which means dropping all the extra permissions it would otherwise have, as - well as access to the session/system/a11y busses and document portal. + well as access to the session/system/a11y buses and document portal.

--log-session-bus

Log session bus traffic. This can be useful to see what access you need to allow in your D-Bus policy. @@ -3462,6 +3697,14 @@ either with the --sideload-repo option, or on a per-installation or system-wide basis (see flatpak(1)). +

+ For OCI remotes, sideload repositories can also be specified as + --sideload-repo=oci:PATH or --sideload-repo=oci-archive:PATH, + where path points to an OCI image layout or archive of an OCI image layout. + (See containers-transports(5).) + When specified in this fashion, the images found in the image layout are available for all OCI remotes, + without regard to collection ID. For this reason, there is no directory equivalent - + it can only be specified on the command line.

Note that updating a runtime is different from installing a different branch, and runtime updates are expected to keep @@ -3675,7 +3918,7 @@ It is recommended to use this key over DeployCollectionID or CollectionID because only newer clients (Flatpak 1.12.8 or later) pay attention to it (and older clients don't handle collection IDs properly). -

DeployCollectionID (string)

This is deprecated but still supported for backwards compatibility. Use DeploySideloadCollectionID instead.

CollectionID (string)

This is deprecated but still supported for backwards compatibility. Use DeploySideloadCollectionID instead.

IsRuntime (boolean)

Whether this file refers to a runtime. If this key is not specified, the file is assumed to refer to an application.

GPGKey (string)

The base64-encoded gpg key for the remote.

RuntimeRepo (string)

The url for a .flatpakrepo file for the remote where the runtime can be found. +

DeployCollectionID (string)

This is deprecated but still supported for backwards compatibility. Use DeploySideloadCollectionID instead.

CollectionID (string)

This is deprecated but still supported for backwards compatibility. Use DeploySideloadCollectionID instead.

IsRuntime (boolean)

Whether this file refers to a runtime. If this key is not specified, the file is assumed to refer to an application.

GPGKey (string)

The base64-encoded gpg key for the remote.

SignatureLookaside (string)

URL to use to look up signatures (OCI remotes only)

RuntimeRepo (string)

The url for a .flatpakrepo file for the remote where the runtime can be found. Note that if the runtime is available in the remote providing the app, that remote may be used instead but the one specified by this option will still be added.

SuggestRemoteName (string)

A suggested name for the remote.

Example

 [Flatpak Ref]
@@ -3763,12 +4006,97 @@

[Context]

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

+

Conditional Permissions

+ Some permissions (such as sockets and + devices) support conditional grants, + where access is only provided when specific runtime + conditions are met. This allows applications to adapt + to different system capabilities and session types. + Available since 1.17. +

+ Conditional permissions use the syntax + if:PERMISSION:CONDITION in the + metadata file. For example, + if:wayland:has-wayland grants + Wayland socket access only when running in a Wayland session. +

+ The following conditions are supported: +

true

+ Always evaluates to true. +

false

+ Always evaluates to false. +

has-input-device

+ True if this version of Flatpak supports the + input device permission. + This is always true in Flatpak 1.15.6 and later, + and can be used to provide fallback behavior for + older Flatpak versions. +

has-wayland

+ True if the current desktop session supports + Wayland. +

has-usb-device

+ True if this version of Flatpak supports the + usb device permission. + This is always true in Flatpak 1.16.0 and later, + and can be used to provide fallback behavior for + older Flatpak versions. +

has-usb-portal

+ True if the current desktop session supports + the USB Portal. +

+ Conditions can be negated by prefixing with + !. For example, + if:x11:!has-wayland grants + X11 socket access only when NOT running in a Wayland session. +

+ Multiple conditional permissions can be specified for + the same resource. If any condition matches, the + permission is granted (OR logic). For example: +

+sockets=wayland;if:x11:!has-wayland;if:x11:false
+

+

+ For backward compatibility with older Flatpak versions, + conditional permissions can be combined with unconditional + grants: +

+sockets=x11;if:x11:!has-wayland;
+

+ Older Flatpak versions will grant X11 access unconditionally + (seeing only x11), while newer + versions recognize the conditional syntax and grant + X11 access only when not in Wayland sessions. +

+ To explicitly deny a permission that might be granted at + a lower layer (such as from the runtime or a global override), + prefix the permission name with !: +

+sockets=!x11;
+

+ This denial can be combined with conditional grants to + remove unconditional access while allowing conditional access: +

+sockets=!x11;x11;if:x11:!has-wayland;
+

+ This denies unconditional X11 access, but allows X11 + access conditionally when not running in a Wayland session. + The seemingly contradictory !x11 and + x11 ensures backward compatibility: + older Flatpak versions see the final x11 + grant, while newer versions understand the conditional logic. +

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

+ The keys supported in this group are:

shared (list)

List of subsystems to share with the host system. Possible subsystems: network, ipc. Available since 0.3. +

+ This option supports conditional permissions. + See Conditional Permissions + for details on how to share subsystem access conditionally + based on runtime conditions.

sockets (list)

List of well-known sockets to make available in the sandbox. Possible sockets: x11, wayland, fallback-x11, pulseaudio, session-bus, system-bus, @@ -3778,14 +4106,20 @@ DBUS_SYSTEM_BUS_ADDRESS to let the application find sockets that are not in a fixed location. Available since 0.3. +

+ This option supports conditional permissions. + See Conditional Permissions + for details on how to grant socket access conditionally + based on runtime conditions.

devices (list)

List of devices to make available in the sandbox. This just expose the devices nodes, it doesn't grant any permission that the user doesn't already have. Possible values:

dri

- Graphics direct rendering - (/dev/dri). + GPU graphics and compute + (/dev/dri), including + vendor specific render and compute devices. Available since 0.3.

input

Input devices @@ -3808,6 +4142,11 @@ (/dev/shm). Available since 1.6.1.

+

+ This option supports conditional permissions. + See Conditional Permissions + for details on how to grant device access conditionally + based on runtime conditions.

filesystems (list)

List of filesystem subsets to make available to the application. Possible values: @@ -4060,6 +4399,11 @@ indicate the absence of that feature, for example !devel if development and debugging are not allowed. +

+ This option supports conditional permissions. + See Conditional Permissions + for details on how to allow features based + conditionally on runtime conditions.

unset-environment (list)

A list of names of environment variables to unset. Note that environment variables to set to a value @@ -4395,11 +4739,11 @@ syntax the arguments to `--usb`. Available since 1.15.11.

hidden-devices (string list)

- List of hidden USB devices, i.e. to remove the enumarable + List of hidden USB devices, i.e. to remove the enumerable devices list. Each element is the same syntax the arguments to `--nousb`. Hidden devices take precedence over enumerable devices. Available since 1.15.11. -

Example

+

Example

 [Application]
 name=org.gnome.Calculator
 runtime=org.gnome.Platform/x86_64/3.20
@@ -4427,11 +4771,28 @@
 
 [Extension org.gnome.Calculator.Debug]
 directory=lib/debug
-

See also

+

+ Example using conditional permissions to support fallback + from Wayland to X11: + 

+[Application]
+name=org.example.App
+runtime=org.gnome.Platform/x86_64/3.20
+sdk=org.gnome.Sdk/x86_64/3.20
+
+[Context]
+shared=network;ipc;
+sockets=wayland;x11;if:x11:!has-wayland;
+

+ In this example, the application will always have access to + the Wayland socket if there the app runs in a Wayland session. + The X11 socket only is available if the app does not run in + a wayland session (!has-wayland). +

See also

flatpak(1), flatpak-run(1), flatpak-override(1) -

Name

flatpak-remote — Configuration for a remote

Description

+

Name

flatpak-remote — Configuration for a remote

Description

Flatpak stores information about configured remotes for an installation location in $installation/repo/config. For example, the remotes for the default system-wide installation are in @@ -4447,10 +4808,10 @@ /etc/flatpak/remotes.d/. Ifa file with the same name exists in both, the file under /etc will take precedence. -

File format

+

File format

The remote config file format is using the same .ini file format that is used for systemd unit files or application .desktop files. -

[remote …]

+

[remote …]

All the configuration for the the remote with name NAME is contained in the [remote "NAME"] group.

@@ -4470,7 +4831,10 @@

xa.disable (boolean)

Whether the remote is disabled. Defaults to false.

xa.prio (integer)

The priority for the remote. This is used when listing remotes, and when searching them for the runtime needed by an app. The remote providing the app is searched for its runtime before others with equal priority. Defaults to 1.

xa.noenumerate (boolean)

Whether this remote should be ignored when presenting available apps/runtimes, - or when searching for a runtime dependency. Defaults to false.

xa.nodeps (boolean)

Whether this remote should be excluded when searching for dependencies. Defaults to false.

xa.title (string)

An optional title to use when presenting this remote in a UI.

xa.title-is-set (boolean)

This key is set to true if xa.title has been explicitly set.

xa.comment (string)

An optional single-line comment to use when presenting this remote in a UI.

xa.comment-is-set (boolean)

This key is set to true if xa.comment has been explicitly set.

xa.description (string)

An optional full-paragraph of text to use when presenting this remote in a UI.

xa.description-is-set (boolean)

This key is set to true if xa.description has been explicitly set.

xa.homepage (string)

An optional URL that points to a website for this repository to use when presenting this remote in a UI.

xa.homepage-is-set (boolean)

This key is set to true if xa.homepage has been explicitly set.

xa.icon (string)

An optional URL that points to an icon for this repository to use when presenting this remote in a UI.

xa.icon-is-set (boolean)

This key is set to true if xa.icon has been explicitly set.

xa.default-branch (string)

The default branch to use when installing from this remote.

xa.default-branch-is-set (boolean)

This key is set to true if xa.default-branch has been explicitly set.

xa.main-ref (string)

The main reference served by this remote. This is used for origin remotes of applications installed via a flatpakref file.

Examples

+                    or when searching for a runtime dependency. Defaults to false.
xa.nodeps (boolean)
Whether this remote should be excluded when searching for dependencies. Defaults to false.
xa.title (string)
An optional title to use when presenting this remote in a UI.
xa.title-is-set (boolean)
This key is set to true if xa.title has been explicitly set.
xa.comment (string)
An optional single-line comment to use when presenting this remote in a UI.
xa.comment-is-set (boolean)
This key is set to true if xa.comment has been explicitly set.
xa.description (string)
An optional full-paragraph of text to use when presenting this remote in a UI.
xa.description-is-set (boolean)
This key is set to true if xa.description has been explicitly set.
xa.homepage (string)
An optional URL that points to a website for this repository to use when presenting this remote in a UI.
xa.homepage-is-set (boolean)
This key is set to true if xa.homepage has been explicitly set.
xa.icon (string)
An optional URL that points to an icon for this repository to use when presenting this remote in a UI.
xa.icon-is-set (boolean)
This key is set to true if xa.icon has been explicitly set.
xa.default-branch (string)
The default branch to use when installing from this remote.
xa.default-branch-is-set (boolean)
This key is set to true if xa.default-branch has been explicitly set.
xa.main-ref (string)
The main reference served by this remote. This is used for origin remotes of applications installed via a flatpakref file.
xa.signature-lookaside (string)
URL to load signatures from (OCI remotes only),
+                    using the 
+                    containers/image separate storage mechanism.
+

Examples

 [remote "gnome-nightly-apps"]
 gpg-verify=true
 gpg-verify-summary=true
@@ -4483,6 +4847,6 @@
 collection-id=org.flathub.Stable
 url=https://dl.flathub.org/repo/
 xa.title=Flathub
-

See also

+

See also

flatpak-remote-modify(1)

\ No newline at end of file From 708a54643953b1870736b203942dfd2daabe9588 Mon Sep 17 00:00:00 2001 From: bbhtt Date: Wed, 1 Jul 2026 09:38:09 +0530 Subject: [PATCH 2/3] Update various link redirects --- docs/available-runtimes.rst | 2 +- docs/conf.py | 2 +- docs/conventions.rst | 10 +++++----- docs/debugging.rst | 2 +- docs/electron.rst | 8 ++++---- docs/extension.rst | 8 ++++---- docs/first-build.rst | 2 +- docs/flatpak-devel.rst | 2 +- docs/hosting-a-repository.rst | 8 ++++---- docs/index.rst | 2 +- docs/manifests.rst | 8 ++++---- docs/module-sources.rst | 6 +++--- docs/python.rst | 2 +- docs/qt.rst | 2 +- docs/single-file-bundles.rst | 2 +- docs/tips-and-tricks.rst | 2 +- docs/using-flatpak.rst | 4 ++-- 17 files changed, 36 insertions(+), 36 deletions(-) diff --git a/docs/available-runtimes.rst b/docs/available-runtimes.rst index fa71fcad..11933181 100644 --- a/docs/available-runtimes.rst +++ b/docs/available-runtimes.rst @@ -54,7 +54,7 @@ based on the Freedesktop runtime and adds the libraries and components used by the GNOME platform. Major version releases of the runtime are synced with `GNOME releases `_ -and are announced on `GNOME Discourse `_. +and are announced on `GNOME Discourse `_. Usually a given branch of the runtime is supported for a year and EOL-ed upon the release of a newstable version. diff --git a/docs/conf.py b/docs/conf.py index 143e1e96..bb736c70 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -157,7 +157,7 @@ linkcheck_anchors_ignore_for_url = [ r'https://github\.com/.*', r'https://gitlab\.com/.*', - r'https://hg\.mozilla\.org/.*', + r'https://hg-edge\.mozilla\.org/.*', r'https://gitlab\.gnome\.org/GNOME/Initiatives/-/wikis/DevOps-with-Flatpak' ] diff --git a/docs/conventions.rst b/docs/conventions.rst index 49a47cb6..d27d8693 100644 --- a/docs/conventions.rst +++ b/docs/conventions.rst @@ -33,7 +33,7 @@ Developers must follow the standard `D-Bus naming conventions for bus names `_ when creating their own IDs. This format is already recommended by the `Desktop File specification -`_ +`_ and also the `Appstream specification `_. @@ -119,7 +119,7 @@ Application icons Applications are expected to provide an application icon, which is used for their application launcher. These icons should be provided in accordance with the `Freedesktop icon specification -`_. +`_. Icons must be named using the application's ID, be in either PNG or SVG format, and must be placed in the standard location:: @@ -152,7 +152,7 @@ Desktop files Desktop files are used to provide the desktop environment with information about each application. The `Freedesktop specification -`_ +`_ provides a complete reference for writing desktop files. Desktop files must be named using the application's ID, followed @@ -296,7 +296,7 @@ is provided below:: - the "fdo #xxxxx" are the wish in the freedesktop.org bug database to include the mime type there. --> - + iCal Calendar Event Component @@ -357,7 +357,7 @@ XDG base directories -------------------- `XDG base directories -`_ are +`_ are standard locations for user-specific application data. Popular toolkits provide convenience functions for accessing XDG base directories. These include: diff --git a/docs/debugging.rst b/docs/debugging.rst index 57883f0a..6fb321cc 100644 --- a/docs/debugging.rst +++ b/docs/debugging.rst @@ -101,7 +101,7 @@ Getting stacktraces from a crash -------------------------------- If an application crashed and the system has coredumps and -`systemd-coredump `_ +`systemd-coredump `_ enabled, a coredump will be logged. Get the ``PID`` from that coredump:: $ coredumpctl list diff --git a/docs/electron.rst b/docs/electron.rst index 13d38533..bb62fd76 100644 --- a/docs/electron.rst +++ b/docs/electron.rst @@ -11,9 +11,9 @@ from other applications. It also includes information on the tooling for building Electron applications and how to use it. The guide walks through the `manifest file -`_ +`_ of the `sample Electron Flatpak application -`_. Before you start, +`_. Before you start, it is a good idea to take a look at this, either online or by downloading the application. @@ -228,7 +228,7 @@ and hash of the application are also specified. subdir: main sources: - type: archive - url: https://github.com/flathub/electron-sample-app/archive/1.0.1.tar.gz + url: https://github.com/flathub/org.flathub.electron-sample-app/archive/1.0.1.tar.gz sha256: a2feb3f1cf002a2e4e8900f718cc5c54db4ad174e48bfcfbddcd588c7b716d5b dest: main @@ -320,6 +320,6 @@ The preferred way of fixing this, is not a patch, but a build-time edit using `` Make setProgressBar and setBadgeCount work ------------------------------------------- The `setProgressBar `_ and `setBadgeCount `_ functions allow showing a progress bar and a badge count in the window icon. It is implemented under Linux using the `UnityLauncherAPI `_. This API is not implemented on every desktop environment. A known desktop environment which implements this is KDE. -It is also implemented by the popular `Dash to Dock `_ GNOME extension and `Plank `_. +It is also implemented by the popular `Dash to Dock `_ GNOME extension and `Plank `_. To make it work in Flatpak, the app needs to :ref:`use the correct desktop filename ` in its embedded `package.json` file. The Flatpak also needs the ``--talk-name=com.canonical.Unity`` permission. Electron versions earlier than v32 checks `checks if it's running on Unity or KDE `_ before using the UnityLauncherAPI. diff --git a/docs/extension.rst b/docs/extension.rst index ff029988..d6ee4ec9 100644 --- a/docs/extension.rst +++ b/docs/extension.rst @@ -137,7 +137,7 @@ extension points. An example of an extension point defined in runtime is the GL extension point used in `Freedesktop SDK `_ -Freedesktop SDK uses `buildstream `_, +Freedesktop SDK uses `buildstream `_, so the `format `_ is different from the usual ``json`` or ``yaml`` format used by Flatpak manifests. @@ -456,7 +456,7 @@ stores. This is a typical example of an extension MetaInfo file. Bar - https://flatpak.github.io/ + https://flatpak.org/ bar_AT_example.org @@ -518,7 +518,7 @@ the same as above. An example of an unmaintained extension can be found in browsers such as `Chromium `_ -or `Firefox `_ +or `Firefox `_ on Flathub. The Firefox snippet translates to: @@ -538,7 +538,7 @@ and ``/var/lib/flatpak/extension/org.mozilla.firefox.systemconfig/x86_64/stable/ (or in ``$XDG_DATA_HOME/flatpak/extension/...``) respectively on host. The path here is dependent on the extension point. These would appear under ``/app/etc/firefox/policies/policies.json`` and -``/app/etc/firefox/defaults/pref`` inside the sandbox. (Firefox `supports `_ +``/app/etc/firefox/defaults/pref`` inside the sandbox. (Firefox `supports `_ reading policies from ``/app/etc``) For details on Chromium, please look at the diff --git a/docs/first-build.rst b/docs/first-build.rst index 535ac139..35aec2a3 100644 --- a/docs/first-build.rst +++ b/docs/first-build.rst @@ -95,7 +95,7 @@ See :doc:`single-file-bundles` for more details on it. .. code-block:: bash - flatpak build-bundle repo hello.flatpak org.flatpak.Hello --runtime-repo=https://flathub.org/repo/flathub.flatpakrepo + flatpak build-bundle repo hello.flatpak org.flatpak.Hello --runtime-repo=https://dl.flathub.org/repo/flathub.flatpakrepo Now you can send the ``hello.flatpak`` file to someone and if they have the Flathub repository set up and a working network connection to install diff --git a/docs/flatpak-devel.rst b/docs/flatpak-devel.rst index e4d5eedc..e2e1308b 100644 --- a/docs/flatpak-devel.rst +++ b/docs/flatpak-devel.rst @@ -365,7 +365,7 @@ desktop file to fix the window class. Additional tools ---------------- -- `Electron Builder `_ +- `Electron Builder `_ supports exporting single file Flatpak bundles. Please also see the Electron application packaging guide :doc:`electron`. diff --git a/docs/hosting-a-repository.rst b/docs/hosting-a-repository.rst index 0f5d77c5..10205831 100644 --- a/docs/hosting-a-repository.rst +++ b/docs/hosting-a-repository.rst @@ -131,7 +131,7 @@ The instructions will use Gitlab.com. - $MANIFEST_PATH expire_in: 1 week rules: - # Set up a pipeline schedule for this https://docs.gitlab.com/ee/ci/pipelines/schedules.html + # Set up a pipeline schedule for this https://docs.gitlab.com/ci/pipelines/schedules/ - if: $CI_PIPELINE_SOURCE == "schedule" || $CI_PIPELINE_SOURCE == "trigger" when: always - when: never @@ -141,7 +141,7 @@ The instructions will use Gitlab.com. image: ${DOCKER_IMAGE} variables: # Stable Flathub repo - RUNTIME_REPO: "https://flathub.org/repo/flathub.flatpakrepo" + RUNTIME_REPO: "https://dl.flathub.org/repo/flathub.flatpakrepo" script: # Set up an user as the docker image used here comes with none - | @@ -351,7 +351,7 @@ This uses Gitlab.com's `hosted aarch64 runners `_. +run applications, please refer to `the Flatpak website `_. Contents -------- diff --git a/docs/manifests.rst b/docs/manifests.rst index 729515f0..ae4612b3 100644 --- a/docs/manifests.rst +++ b/docs/manifests.rst @@ -292,7 +292,7 @@ An example is provided below. - PREFIX=/app sources: - type: git - url: https://github.com/FFmpeg/nv-codec-headers.git + url: https://github.com/FFmpeg/nv-codec-headers commit: 43d91706e097565f57b311e567f0219838bcc2f6 tag: n11.1.5.3 @@ -304,7 +304,7 @@ An example is provided below. - -Dtests=false sources: - type: git - url: https://gitlab.freedesktop.org/mesa/drm.git + url: https://gitlab.freedesktop.org/mesa/libdrm.git tag: libdrm-2.4.124 # Using simple @@ -315,7 +315,7 @@ An example is provided below. - make -j$FLATPAK_BUILDER_N_JOBS PREFIX=/app install sources: - type: git - url: https://github.com/FFmpeg/nv-codec-headers.git + url: https://github.com/FFmpeg/nv-codec-headers commit: 43d91706e097565f57b311e567f0219838bcc2f6 tag: n11.1.5.3 @@ -326,7 +326,7 @@ An example is provided below. - ninja -C builddir install sources: - type: git - url: https://gitlab.freedesktop.org/mesa/drm.git + url: https://gitlab.freedesktop.org/mesa/libdrm.git tag: libdrm-2.4.124 Shared Modules diff --git a/docs/module-sources.rst b/docs/module-sources.rst index 99f0432a..05321e8d 100644 --- a/docs/module-sources.rst +++ b/docs/module-sources.rst @@ -71,7 +71,7 @@ where the given source will be placed: url: https://example.org/foo.tar.xz sha256: 834b06e423d360c97197e7abec99b623fdc5ed3a0c39b88d6467e499074585e1 - type: git - url: https://github.com/foo/bar.git + url: https://github.com/foo/bar commit: 3f9389edc6cdf3f78a6896d550c236860aed62b2 dest: 'src/deps/bar' @@ -253,7 +253,7 @@ A typical example is: - install -Dpm755 -t "${FLATPAK_DEST}/bin" squashfs-tools/unsquashfs sources: - type: git - url: https://github.com/plougher/squashfs-tools.git + url: https://github.com/plougher/squashfs-tools tag: 4.6.1 commit: d8cb82d9840330f9344ec37b992595b5d7b44184 @@ -585,7 +585,7 @@ manifest root path, whose contents will be copied during build. path: icons Additonally there are `bzr`, `svn` and `inline` sources supported. -`bzr` and `svn` requires the `bzr `_ +`bzr` and `svn` requires the `bzr `_ and `svn `_ commandline tools to be installed respectively. Please see :doc:`flatpak-builder-command-reference` for them. diff --git a/docs/python.rst b/docs/python.rst index 213f3477..3e8c6494 100644 --- a/docs/python.rst +++ b/docs/python.rst @@ -21,7 +21,7 @@ rather straightforward: - pip3 install --prefix=/app --no-deps . sources: - type: archive - url: https://files.pythonhosted.org/packages/source/r/requests/requests-2.18.4.tar.gz + url: https://files.pythonhosted.org/packages/b0/e1/eab4fc3752e3d240468a8c0b284607899d2fbfb236a56b7377a329aa8d09/requests-2.18.4.tar.gz sha256: 9c443e7324ba5b85070c4a818ade28bfabedf16ea10206da1132edaa6dda237e Here, ``build-commands`` is an array containing the commands required to diff --git a/docs/qt.rst b/docs/qt.rst index e93affc7..2fe5c4f5 100644 --- a/docs/qt.rst +++ b/docs/qt.rst @@ -27,7 +27,7 @@ straight-forward. - -DCMAKE_BUILD_TYPE=RelWithDebInfo sources: - type: archive - url: https://github.com/flatpak/qt-flatpak-demo/archive/v1.1.2.tar.gz + url: https://codeload.github.com/flatpak/qt-flatpak-demo/tar.gz/refs/tags/v1.1.2 sha256: 1a1cc5d0f06ad949d6854c772ec9624b8856a0a4f880355f51058bc0dd52ba7a Contents diff --git a/docs/single-file-bundles.rst b/docs/single-file-bundles.rst index 9fe538bc..284023a0 100644 --- a/docs/single-file-bundles.rst +++ b/docs/single-file-bundles.rst @@ -27,7 +27,7 @@ GNOME dictionary app from the repository at ~/repositories/apps, run:: You can also set a runtime repo in the bundle:: - $ flatpak build-bundle ~/repositories/apps dictionary.flatpak org.gnome.Dictionary --runtime-repo=https://flathub.org/repo/flathub.flatpakrepo + $ flatpak build-bundle ~/repositories/apps dictionary.flatpak org.gnome.Dictionary --runtime-repo=https://dl.flathub.org/repo/flathub.flatpakrepo To import the bundle into a repository on another machine, run:: diff --git a/docs/tips-and-tricks.rst b/docs/tips-and-tricks.rst index cae3e3e0..cc77095d 100644 --- a/docs/tips-and-tricks.rst +++ b/docs/tips-and-tricks.rst @@ -156,7 +156,7 @@ create a ``flatpak`` directory so the path specified by ``Path=`` exists. Then you can add a remote using a command like:: - $ flatpak --installation=extra remote-add flathub https://flathub.org/repo/flathub.flatpakrepo + $ flatpak --installation=extra remote-add flathub https://dl.flathub.org/repo/flathub.flatpakrepo And install to it with:: diff --git a/docs/using-flatpak.rst b/docs/using-flatpak.rst index f1029443..c106da47 100644 --- a/docs/using-flatpak.rst +++ b/docs/using-flatpak.rst @@ -97,7 +97,7 @@ Add a remote The most convenient way to add a remote is by using a ``.flatpakrepo`` file, which includes both the details of the remote and its GPG key:: - $ flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo + $ flatpak remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo Here, ``flathub`` is the local name that is given to the remote. The URL points to the remote's ``.flatpakrepo`` file. ``--if-not-exists`` stops the @@ -142,7 +142,7 @@ The details of the application to be installed can also be provided by a ``.flatpakref`` instead of manually providing the remote and application ID, run:: - $ flatpak install https://flathub.org/repo/appstream/org.gimp.GIMP.flatpakref + $ flatpak install https://dl.flathub.org/repo/appstream/org.gimp.GIMP.flatpakref If the ``.flatpakref`` file specifies that the application is to be installed from a remote that hasn't already been added, you will be asked whether to From 967d30dd363dad86116312868345b6d000711ced Mon Sep 17 00:00:00 2001 From: bbhtt Date: Wed, 1 Jul 2026 09:49:33 +0530 Subject: [PATCH 3/3] conf: Allow some redirects --- docs/conf.py | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index bb736c70..5704a8f9 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -174,6 +174,18 @@ } } +linkcheck_allowed_redirects = { + # Locale redirects + r"https://flathub\.org/?": + r"https://flathub\.org/en/?", + + r"https://flathub\.org/apps/.*": + r"https://flathub\.org/en/apps/.*", + + r"https://flatpak\.org/setup": + r"https://flathub\.org(/en)?/setup/?", +} + linkcheck_retries = 2 linkcheck_timeout = 10