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:

name – a remote name
cancellable – a Cancellable

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[[str, int, bool, Any], None] | None = None, progress_data: Any = None, cancellable: Cancellable | None = None) → 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
progress_data – user data passed to progress
cancellable – a Cancellable

install_bundle(file: File, progress: Callable[[str, int, bool, Any], None] | None = None, progress_data: Any = None, cancellable: Cancellable | None = None) → 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
progress_data – user data passed to progress
cancellable – a Cancellable

install_full(flags: InstallFlags, remote_name: str, kind: RefKind, name: str, arch: str | None = None, branch: str | None = None, subpaths: list[str] | None = None, progress: Callable[[str, int, bool, Any], None] | None = None, progress_data: Any = None, cancellable: Cancellable | None = None) → 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.

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
progress_data – user data passed to progress
cancellable – a Cancellable

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 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

list_installed_related_refs_sync(remote_name: str, ref: str, cancellable: Cancellable | None = None) → list[RelatedRef]#

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

list_remote_related_refs_for_installed_sync(remote_name: str, ref: str, cancellable: Cancellable | None = None) → list[RelatedRef]#

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

list_remote_related_refs_sync(remote_name: str, ref: str, cancellable: Cancellable | None = None) → list[RelatedRef]#

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 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: list[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:

types – an array of RemoteType
cancellable – a Cancellable

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[Any, Any] | 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:

remote – the modified Remote
cancellable – a Cancellable

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[[str, int, bool, Any], None] | None = None, progress_data: Any = None, cancellable: Cancellable | None = None) → 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
progress_data – user data passed to progress
cancellable – a Cancellable

uninstall_full(flags: UninstallFlags, kind: RefKind, name: str, arch: str | None = None, branch: str | None = None, progress: Callable[[str, int, bool, Any], None] | None = None, progress_data: Any = None, cancellable: Cancellable | None = None) → 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
progress_data – user data passed to progress
cancellable – a Cancellable

update(flags: UpdateFlags, kind: RefKind, name: str, arch: str | None = None, branch: str | None = None, progress: Callable[[str, int, bool, Any], None] | None = None, progress_data: Any = None, cancellable: Cancellable | None = None) → 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
progress_data – user data passed to progress
cancellable – a Cancellable

update_appstream_full_sync(remote_name: str, arch: str | None = None, progress: Callable[[str, int, bool, Any], None] | None = None, progress_data: Any = None, out_changed: bool | None = None, cancellable: Cancellable | None = None) → 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
progress_data – user data passed to progress
out_changed – Set to True if the contents of the appstream changed, False if nothing changed
cancellable – a Cancellable

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: list[str] | None = None, progress: Callable[[str, int, bool, Any], None] | None = None, progress_data: Any = None, cancellable: Cancellable | None = None) → 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
progress_data – user data passed to progress
cancellable – a Cancellable

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#

Installation#

Constructors#

Methods#

Fields#

This Page