Managing Flatpaks

Management of flatpaks can be performed using graphical applications or command line tools. This document describes how to perform common package management tasks using command line tools.

Note that management of Debian packages is discussed in the Managing Debian Packages section.

Getting Started

It may be useful to review the Concepts and Terminology section before continuing.

Log in to the phone via a serial console or network connection. You should now be able to issue commands at the shell prompt. In this document we prefix each of the commands with the shell prompt to indicate that they are entered at the command line on the phone:

purism@pureos:~$

Next, ensure that the phone has access to the Internet.

Tools

The most useful tool for managing Debian packages is the flatpak tool. This is used to search for packages in remote repositories, request installation of packages and uninstall them when they are no longer needed.

The flatpak tool is already installed on the phone.

Listing Packages

To see the list of flatpaks that are installed on your system, enter the following at the command line:

purism@pureos:~$ flatpak list

This should cause a summary to be shown of the packages that the system knows about, as in the following snippet:

Description                                                                 Application                Version Branch Arch    Origin                Installation
Play Sounds                                                                 com.example.play_sounds            master aarch64 play_sounds-origin    user
Read Buttons                                                                com.example.read_buttons           master aarch64 read_buttons-origin   user
Simple Weather                                                              com.example.simple_weather         master aarch64 simple_weather-origin user
GNOME Application Platform version 45 - Shared libraries used by GNOME a…   org.gnome.Platform                 45     aarch64 flathub               user
GNOME Software Development Kit version 45 - Tools and headers for develo…   org.gnome.Sdk                      45     aarch64 flathub               user

The Application column contains the identifiers that are used to refer to applications when using the command line flatpak tool.

Updating Packages

Packages can be updated to the latest version either individually or as a complete upgrade of all flatpaks.

To update a single flatpak, such as the Simple Weather example, enter the following, using the Application identifier given in the list of installed packages:

purism@pureos:~$ flatpak update com.example.simple_weather

To update all flatpaks, enter the following:

purism@pureos:~$ flatpak update

This should result in output beginning with text like the following:

Looking for updates…

If there are updates available, you will be asked if you want to proceed with their installation. Otherwise, this message will be shown:

Nothing to do.

This indicates that the installed software is up-to-date.

Searching for Software

Applications and other components can be obtained from the remote repositories that are known to the system. For example, the GNOME Weather program can be searched for with the following command:

purism@pureos:~$ flatpak search weather

This will produce a number of suggestions for suitable packages. Amongst these is the relevant package:

Description                                                                                             Application                   Version   Branch  Remotes
Weather - Show weather conditions and forecast                                                          org.gnome.Weather             45        stable  flathub

The name of the package is in the Application column.

Installing Packages

To install a package, simply run the flatpak tool in the following way – in this case to install the GNOME Weather application, using the name obtained above:

purism@pureos:~$ flatpak install org.gnome.weather

If this is successful, the output produced should indicate that the package containing the program was downloaded, unpacked and installed.

Uninstalling Packages

When a piece of software is no longer needed, its package can be uninstalled as in this example, using the same Application name as before:

purism@pureos:~$ flatpak uninstall org.gnome.weather

Uninstalling applications you no longer need will reduce the amount of data you need to download when updates for those applications become available.

Adding and Removing Repositories

By default, you will only be able to install software from the repositories that are provided in the standard configuration for the phone. However, you can change the list of remote repositories (remotes) using the flatpak tool’s collection of commands for managing them.

To list the remotes known to the system, enter the following:

purism@pureos:~$ flatpak remotes

Add a remote in the following way – in this case, adding the Nightly GNOME Apps remote to the list of known remotes:

flatpak remote-add --if-not-exists gnome-nightly https://nightly.gnome.org/gnome-nightly.flatpakrepo

Remove a remote with the corresponding command:

flatpak remote-delete gnome-nightly

It can be useful to remove repositories that provide old versions or duplicates of software. This will make searching for packages quicker.