Installation

class Installation(**properties: Any)

Superclasses: Object

Constructors:

Installation(**properties)
new_for_path(path:Gio.File, user:bool, cancellable:Gio.Cancellable=None) -> Flatpak.Installation
new_system(cancellable:Gio.Cancellable=None) -> Flatpak.Installation
new_system_with_id(id:str=None, cancellable:Gio.Cancellable=None) -> Flatpak.Installation
new_user(cancellable:Gio.Cancellable=None) -> Flatpak.Installation

Constructors

class Installation
classmethod new_for_path(path: File, user: bool, cancellable: Cancellable | None = None) → Installation

Creates a new Installation for the installation at the given path.

Parameters:

  • path – a File

  • user – whether this is a user-specific location

  • cancellable – a Cancellable

classmethod new_system(cancellable: Cancellable | None = None) → Installation

Creates a new Installation for the default system-wide installation.

Parameters:

cancellable – a Cancellable

classmethod new_system_with_id(id: str | None = None, cancellable: Cancellable | None = None) → Installation

Creates a new Installation for the system-wide installation id.

Added in version 0.8.

Parameters:

  • id – the ID of the system-wide installation

  • cancellable – a Cancellable

classmethod new_user(cancellable: Cancellable | None = None) → Installation

Creates a new Installation for the per-user installation.

Parameters:

cancellable – a Cancellable

Methods

class Installation
add_remote(remote: Remote, if_needed: bool, cancellable: Cancellable | None = None) → bool

Adds a new remote object to the set of remotes. This is similar to modify_remote() for non-existing remote names. However, if the named remote already exists then instead of modifying it it fails with ALREADY_INSTALLED, or if if_needed is true it silently succeeds without doing anything.

As an exception to the last, if the local config has a filter defined, but the new remote unsets the filter (for example, it comes from an unfiltered .flatpakref via new_from_file()) the the local remote filter gets reset. This is to allow the setup where there is a default setup of a filtered remote, yet you can still use the standard flatpakref file to get the full contents without getting two remotes.

Added in version 1.3.4.

Parameters:

  • remote – the new Remote

  • if_needed – if True, only add if it doesn’t exists

  • cancellable – a Cancellable

cleanup_local_refs_sync(cancellable: Cancellable | None = None) → bool

Remove all OSTree refs from the local flatpak repository which are not in a deployed state. The next time the underlying OSTree repo is pruned, objects which were attached to that ref will be removed. This is useful if you pulled a flatpak refs using install_full() and specified NO_DEPLOY but then decided not to deploy the refs later on and want to remove the local refs to prevent them from taking up disk space. Note that this will not remove the objects referred to by ref from the underlying OSTree repo, you should use prune_local_repo() to do that.

Added in version 0.10.0.

Parameters:

cancellable – a Cancellable

create_monitor(cancellable: Cancellable | None = None) → FileMonitor

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

Parameters:

cancellable – a Cancellable

drop_caches(cancellable: Cancellable | None = None) → bool

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:

cancellable – a Cancellable

fetch_remote_metadata_sync(remote_name: str, ref: Ref, cancellable: Cancellable | None = None) → Bytes

Obtains the metadata file from a commit.

NOTE: Since 0.11.4 this information is accessible in FlatpakRemoteRef, so this function is not very useful anymore.

Parameters:

  • remote_name – the name of the remote

  • ref – the ref

  • cancellable – a Cancellable

fetch_remote_size_sync(remote_name: str, ref: Ref, cancellable: Cancellable | None = None) → tuple[bool, int, int]

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.

NOTE: Since 0.11.4 this information is accessible in FlatpakRemoteRef, so this function is not very useful anymore.

Parameters:

  • remote_name – the name of the remote

  • ref – the ref

  • cancellable – a Cancellable

get_config(key: str, cancellable: Cancellable | None = None) → str

Get a global configuration option for the installation, see set_config_sync() for supported keys.

Parameters:

  • key – the name of the key to get

  • cancellable – a Cancellable

get_current_installed_app(name: str, cancellable: Cancellable | None = None) → InstalledRef

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

Parameters:

  • name – the name of the app

  • cancellable – a Cancellable

get_default_languages() → list[str]

Get the default languages used by the installation to decide which subpaths to install of locale extensions. This list may also be used by frontends like GNOME Software to decide which language-specific apps to display. An empty array means that all languages should be installed.

Added in version 1.5.0.

get_default_locales() → list[str]

Like get_default_languages() but includes territory information (e.g. en_US rather than en) which may be included in the extra-languages configuration.

Strings returned by this function are in the format specified by `setlocale() <man:setlocale>`_: language[_territory][.codeset][``modifier`]`.

Added in version 1.5.1.

get_display_name() → str

Returns the display name of the installation for self.

Note that this function may return None if the installation does not have a display name.

Added in version 0.8.

get_id() → str

Returns the ID of the installation for self.

The ID for the default system installation is “default”. The ID for the user installation is “user”.

Added in version 0.8.

get_is_user() → bool

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

get_min_free_space_bytes() → tuple[bool, int]

Returns the min-free-space config value from the OSTree repository of this installation.

Applications can use this value, together with information about the available disk space and the size of pending updates or installs, to estimate whether a pull operation will fail due to running out of disk space.

Added in version 1.1.

get_no_interaction() → bool

Returns the value set with set_no_interaction().

Added in version 1.1.1.

get_path() → File

Returns the installation location for self.

get_priority() → int

Returns the numeric priority of the installation for self.

Added in version 0.8.

get_remote_by_name(name: str, cancellable: Cancellable | None = None) → Remote

Looks up a remote by name.

Parameters:
get_storage_type() → StorageType

Returns the type of storage of the installation for self.

Added in version 0.8.

install(remote_name: str, kind: RefKind, name: str, arch: str | None = None, branch: str | None = None, progress: Callable[[...], None] | None = None, cancellable: Cancellable | None = None, *progress_data: Any) → InstalledRef

This is an old deprecated function, you should use Transaction and add_install() instead. It has a lot more interesting features.

Install a new application or runtime.

Note that this function was originally written to always return a InstalledRef. Since 0.9.13, passing FLATPAK_INSTALL_FLAGS_NO_DEPLOY will only pull refs into the local flatpak repository without deploying them, however this function will be unable to provide information on the installed ref, so FLATPAK_ERROR_ONLY_PULLED will be set and the caller must respond accordingly.

Deprecated since version 1.7.0: Use add_install() instead.

Parameters:

  • remote_name – name of the remote to use

  • kind – what this ref contains (an RefKind)

  • name – name of the app/runtime to fetch

  • arch – which architecture to fetch (default: current architecture)

  • branch – which branch to fetch (default: ‘master’)

  • progress – progress callback

  • cancellable – a Cancellable

  • progress_data – user data passed to progress

install_bundle(file: File, progress: Callable[[...], None] | None = None, cancellable: Cancellable | None = None, *progress_data: Any) → InstalledRef

This is an old deprecated function, you should use Transaction and add_install_bundle() instead. It has a lot more interesting features.

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

Deprecated since version 1.7.0: Use add_install_bundle() instead.

Parameters:

  • file – a File that is an flatpak bundle

  • progress – progress callback

  • cancellable – a Cancellable

  • progress_data – user data passed to progress

install_full(flags: InstallFlags, remote_name: str, kind: RefKind, name: str, arch: str | None = None, branch: str | None = None, subpaths: Sequence[str] | None = None, progress: Callable[[...], None] | None = None, cancellable: Cancellable | None = None, *progress_data: Any) → InstalledRef

This is an old deprecated function, you should use Transaction and add_install() instead. It has a lot more interesting features.

Install a new application or runtime.

Note that this function was originally written to always return a InstalledRef. Since 0.9.13, passing FLATPAK_INSTALL_FLAGS_NO_DEPLOY will only pull refs into the local flatpak repository without deploying them, however this function will be unable to provide information on the installed ref, so FLATPAK_ERROR_ONLY_PULLED will be set and the caller must respond accordingly.

Deprecated since version 1.7.0: Use add_install() instead.

Parameters:

  • flags – set of InstallFlags flag

  • remote_name – name of the remote to use

  • kind – what this ref contains (an RefKind)

  • name – name of the app/runtime to fetch

  • arch – which architecture to fetch (default: current architecture)

  • branch – which branch to fetch (default: ‘master’)

  • subpaths – A list of subpaths to fetch, or None for everything

  • progress – progress callback

  • cancellable – a Cancellable

  • progress_data – user data passed to progress

launch(name: str, arch: str | None = None, branch: str | None = None, commit: str | None = None, cancellable: Cancellable | None = None) → bool

Launch an installed application.

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

Parameters:

  • name – name of the app to launch

  • arch – which architecture to launch (default: current architecture)

  • branch – which branch of the application (default: “master”)

  • commit – the commit of branch to launch

  • cancellable – a Cancellable

launch_full(flags: LaunchFlags, name: str, arch: str | None = None, branch: str | None = None, commit: str | None = None, instance_out: Instance | None = None, cancellable: Cancellable | None = None) → bool

Launch an installed application.

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

Compared to launch(), this function returns a Instance that can be used to get information about the running instance. You can also use it to wait for the instance to be done with child_watch_add() if you pass the FLATPAK_LAUNCH_FLAGS_DO_NOT_REAP flag.

Added in version 1.1.

Parameters:

  • flags – set of LaunchFlags

  • name – name of the app to launch

  • arch – which architecture to launch (default: current architecture)

  • branch – which branch of the application (default: “master”)

  • commit – the commit of branch to launch

  • instance_out – return location for a Instance

  • cancellable – a Cancellable

list_installed_refs(cancellable: Cancellable | None = None) → list[InstalledRef]

Lists the installed references.

Parameters:

cancellable – a Cancellable

list_installed_refs_by_kind(kind: RefKind, cancellable: Cancellable | None = None) → list[InstalledRef]

Lists the installed references of a specific kind.

Parameters:

  • kind – the kind of installation

  • cancellable – a Cancellable

list_installed_refs_for_update(cancellable: Cancellable | None = None) → list[InstalledRef]

Lists the installed apps and runtimes that have an update available, either from the configured remote or locally available but not deployed (see set_no_deploy()).

This also checks if any of InstalledRef has a missing RelatedRef (which has should-download set to True) or runtime. If so, it adds the ref to the returning GPtrArray to pull in the RelatedRef or runtime again via an update operation in Transaction.

In case more than one app needs an update of the same runtime or extension, this function will return all of those apps.

Parameters:

cancellable – a Cancellable

Lists all the locally installed refs that are related to ref. These are things that are interesting to install, update, or uninstall together with ref. For instance, locale data or debug information.

Note that while the related refs are usually installed from the same remote as ref (remote_name), it is possible they were installed from another remote.

This function is similar to flatpak_installation_list_remote_related_refs_sync, but instead of looking at what is available on the remote, it only looks at the locally installed refs. This is useful for instance when you’re looking for related refs to uninstall, or when you’re planning to use FLATPAK_UPDATE_FLAGS_NO_PULL to install previously pulled refs.

Added in version 0.6.7.

Parameters:

  • remote_name – the name of the remote providing ref

  • ref – the ref

  • cancellable – a Cancellable

list_pinned_refs(arch: str | None = None, cancellable: Cancellable | None = None) → list[InstalledRef]

Lists the installed references that are pinned, meaning they will not be returned by list_unused_refs() and won’t be removed unless explicitly specified for removal.

Refs appear here either because they have been pinned automatically by Flatpak or because the user pinned them; see flatpak-pin(1).

Added in version 1.9.1.

Parameters:

  • arch – if non-None, the architecture of refs to collect

  • cancellable – a Cancellable

list_remote_refs_sync(remote_or_uri: str, cancellable: Cancellable | None = None) → list[RemoteRef]

Lists all the applications and runtimes in a remote.

Parameters:

  • remote_or_uri – the name or URI of the remote

  • cancellable – a Cancellable

list_remote_refs_sync_full(remote_or_uri: str, flags: QueryFlags, cancellable: Cancellable | None = None) → list[RemoteRef]

Lists all the applications and runtimes in a remote.

Added in version 1.3.3.

Parameters:

  • remote_or_uri – the name or URI of the remote

  • flags – set of QueryFlags

  • cancellable – a Cancellable

Lists all the available refs on remote_name that are related to ref, and which are appropriate for the installed version of ref. For example if the installed version of org.videolan.VLC has a related ref of org.videolan.VLC.Plugin.bdj//3-19.08 and the remote version of VLC has a related ref of org.videolan.VLC.Plugin.bdj//3-20.08, this function will only return the 3-19.08 branch.

See also the related functions list_remote_related_refs_sync() and list_installed_related_refs_sync().

The returned list contains all available related refs, but not every one should always be installed. For example, should_download() returns True if the reference should be installed/updated with the app, and should_delete() returns True if it should be uninstalled with the main ref.

The commit property of each RelatedRef is not guaranteed to be non-None.

Added in version 1.11.1.

Parameters:

  • remote_name – the name of the remote

  • ref – the ref

  • cancellable – a Cancellable

Lists all the available refs on remote_name that are related to ref, and the subpaths to use. These are things that are interesting to install, update, or uninstall together with ref. For instance, locale data or debug information.

The returned list contains all available related refs, but not every one should always be installed. For example, should_download() returns True if the reference should be installed/updated with the app, and should_delete() returns True if it should be uninstalled with the main ref.

The commit property of each RelatedRef is not guaranteed to be non-None.

Added in version 0.6.7.

Parameters:

  • remote_name – the name of the remote

  • ref – the ref

  • cancellable – a Cancellable

list_remotes(cancellable: Cancellable | None = None) → list[Remote]

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

Parameters:

cancellable – a Cancellable

list_remotes_by_type(types: Sequence[RemoteType], cancellable: Cancellable | None = None) → list[Remote]

Lists only the remotes whose type is included in the types argument.

Since flatpak 1.7 this will never return any types except FLATPAK_REMOTE_TYPE_STATIC. Equivalent functionallity to FLATPAK_REMOTE_TYPE_USB can be had by listing remote refs with FLATPAK_QUERY_FLAGS_ONLY_SIDELOADED.

Parameters:
list_unused_refs(arch: str | None = None, cancellable: Cancellable | None = None) → list[InstalledRef]

Lists the installed references that are not ‘used’.

A reference is used if it is either an application, or the runtime or sdk of a used ref, or an extension of a used ref. Pinned runtimes are also considered used; see flatpak-pin(1) and list_pinned_refs().

Added in version 1.1.2.

Parameters:

  • arch – if non-None, the architecture of refs to collect

  • cancellable – a Cancellable

list_unused_refs_with_options(arch: str | None = None, metadata_injection: dict[None, None] | None = None, options: Variant | None = None, cancellable: Cancellable | None = None) → list[InstalledRef]

Like list_unused_refs() but supports an extensible set of options as well as an metadata_injection parameter. The following are currently defined:

  • exclude-refs (as): Act as if these refs are not installed even if they

    are when determining the set of unused refs

  • filter-by-eol (b): Return refs as unused if they are End-Of-Life.

    Note that if this option is combined with other filters then non-EOL refs may also be returned.

  • filter-by-autoprune (b): Return refs as unused if they should be autopruned.

    Note that if this option is combined with other filters then non-autoprune refs may also be returned.

Added in version 1.9.1.

Parameters:

  • arch – if non-None, the architecture of refs to collect

  • metadata_injection – if non-None, a HashTable mapping refs to KeyFile objects, which when available will be used instead of installed metadata

  • options – if non-None, a GVariant a{sv} with an extensible set of options

  • cancellable – a Cancellable

load_app_overrides(app_id: str, cancellable: Cancellable | None = None) → str

Loads the metadata overrides file for an application.

Parameters:

  • app_id – an application id

  • cancellable – a Cancellable

modify_remote(remote: Remote, cancellable: Cancellable | None = None) → bool

Saves changes in the remote object.

Parameters:
prune_local_repo(cancellable: Cancellable | None = None) → bool

Remove all orphaned OSTree objects from the underlying OSTree repo in self.

Added in version 0.10.0.

Parameters:

cancellable – a Cancellable

remove_remote(name: str, cancellable: Cancellable | None = None) → bool

Removes the remote with the given name from the installation.

Parameters:

  • name – the name of the remote to remove

  • cancellable – a Cancellable

run_triggers(cancellable: Cancellable | None = None) → bool

Run the trigger commands to update the files exported by the apps in self. Should be used after one or more app install, upgrade or uninstall operations with the NO_TRIGGERS, NO_TRIGGERS or NO_TRIGGERS flags set.

Added in version 1.0.3.

Parameters:

cancellable – a Cancellable

set_config_sync(key: str, value: str, cancellable: Cancellable | None = None) → bool

Set a global configuration option for the installation, currently the only supported keys are languages, which is a semicolon-separated list of language codes like "sv;en;pl", or "" to mean all languages, and extra-languages, which is a semicolon-separated list of locale identifiers like "en;en_DK;zh_HK.big5hkscs;uz_UZ.utf8``cyrillic`”`.

Parameters:

  • key – the name of the key to set

  • value – the new value, or None to unset

  • cancellable – a Cancellable

set_no_interaction(no_interaction: bool) → None

This method can be used to prevent interactive authorization dialogs to appear for operations on self. This is useful for background operations that are not directly triggered by a user action.

By default, interaction is allowed.

Added in version 1.1.1.

Parameters:

no_interaction – Whether to disallow interactive authorization for operations

uninstall(kind: RefKind, name: str, arch: str | None = None, branch: str | None = None, progress: Callable[[...], None] | None = None, cancellable: Cancellable | None = None, *progress_data: Any) → bool

This is an old deprecated function, you should use Transaction and add_uninstall() instead. It has a lot more interesting features.

Uninstall an application or runtime.

Deprecated since version 1.7.0: Use add_uninstall() instead.

Parameters:

  • kind – what this ref contains (an RefKind)

  • name – name of the app or runtime to uninstall

  • arch – architecture of the app or runtime to uninstall; if None, get_default_arch() is assumed

  • branch – name of the branch of the app or runtime to uninstall; if None, master is assumed

  • progress – the callback

  • cancellable – a Cancellable

  • progress_data – user data passed to progress

uninstall_full(flags: UninstallFlags, kind: RefKind, name: str, arch: str | None = None, branch: str | None = None, progress: Callable[[...], None] | None = None, cancellable: Cancellable | None = None, *progress_data: Any) → bool

This is an old deprecated function, you should use Transaction and add_uninstall() instead. It has a lot more interesting features.

Uninstall an application or runtime.

Added in version 0.11.8.

Deprecated since version 1.7.0: Use add_uninstall() instead.

Parameters:

  • flags – set of UninstallFlags flags

  • kind – what this ref contains (an RefKind)

  • name – name of the app or runtime to uninstall

  • arch – architecture of the app or runtime to uninstall; if None, get_default_arch() is assumed

  • branch – name of the branch of the app or runtime to uninstall; if None, master is assumed

  • progress – the callback

  • cancellable – a Cancellable

  • progress_data – user data passed to progress

update(flags: UpdateFlags, kind: RefKind, name: str, arch: str | None = None, branch: str | None = None, progress: Callable[[...], None] | None = None, cancellable: Cancellable | None = None, *progress_data: Any) → InstalledRef

This is an old deprecated function, you should use Transaction and add_update() instead. It has a lot more interesting features.

Update an application or runtime.

If the specified package is not installed, then NOT_INSTALLED will be thrown.

If no updates could be found on the remote end and the package is already up to date, then ALREADY_INSTALLED will be thrown.

Deprecated since version 1.7.0: Use add_update() instead.

Parameters:

  • flags – set of UpdateFlags 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)

  • branch – name of the branch of the app or runtime to update (default: master)

  • progress – the callback

  • cancellable – a Cancellable

  • progress_data – user data passed to progress

update_appstream_full_sync(remote_name: str, arch: str | None = None, progress: Callable[[...], None] | None = None, out_changed: bool | None = None, cancellable: Cancellable | None = None, *progress_data: Any) → bool

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

Parameters:

  • remote_name – the name of the remote

  • arch – Architecture to update, or None for the local machine arch

  • progress – progress callback

  • out_changed – Set to True if the contents of the appstream changed, False if nothing changed

  • cancellable – a Cancellable

  • progress_data – user data passed to progress

update_appstream_sync(remote_name: str, arch: str | None = None, out_changed: bool | None = None, cancellable: Cancellable | None = None) → bool

Updates the local copy of appstream for remote_name for the specified arch. If you need progress feedback, use update_appstream_full_sync().

Parameters:

  • remote_name – the name of the remote

  • arch – Architecture to update, or None for the local machine arch

  • out_changed – Set to True if the contents of the appstream changed, False if nothing changed

  • cancellable – a Cancellable

update_full(flags: UpdateFlags, kind: RefKind, name: str, arch: str | None = None, branch: str | None = None, subpaths: Sequence[str] | None = None, progress: Callable[[...], None] | None = None, cancellable: Cancellable | None = None, *progress_data: Any) → InstalledRef

This is an old deprecated function, you should use Transaction and add_update() instead. It has a lot more interesting features.

Update an application or runtime.

If the specified package is not installed, then NOT_INSTALLED will be thrown.

If no updates could be found on the remote end and the package is already up to date, then ALREADY_INSTALLED will be thrown.

Deprecated since version 1.7.0: Use add_update() instead.

Parameters:

  • flags – set of UpdateFlags 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)

  • branch – name of the branch of the app or runtime to update (default: master)

  • subpaths – A list of subpaths to fetch, or None for everything

  • progress – the callback

  • cancellable – a Cancellable

  • progress_data – user data passed to progress

update_remote_sync(name: str, cancellable: Cancellable | None = None) → bool

Updates the local configuration of a remote repository by fetching the related information from the summary file in the remote OSTree repository and committing the changes to the local installation.

Added in version 0.6.13.

Parameters:

  • name – the name of the remote to update

  • cancellable – a Cancellable

Fields

class Installation
parent