Getting Started

Fedora Sway Atomic is designed to be easy and straightforward to use, and specialist knowledge should generally not be required. However, Fedora Sway Atomic is built differently from other operating systems, and there are therefore some things that it is useful to know.

Fedora Sway Atomic has different options for installing software, compared with a standard Fedora Sway Spin (or other package-based Linux distributions). These include:

  • Flatpak apps: this is the primary way that (GUI) apps get installed on Fedora Sway Atomic.

  • Toolbox: Used primarily for CLI apps; development, debugging tools, etc., but also has support for graphical apps.

  • Package layering: Most Fedora packages can be installed on the system with the help of package layering. By default the system operates in pure image mode, but package layering is useful for things like libvirt, drivers, etc.

For information on Flatpak and package layering, see below.

See the dedicated toolbox page to get started with it.


Flatpak is the primary way that apps can be installed on Fedora Sway Atomic (for more information, see Flatpak works out of the box in Fedora Sway Atomic, and Fedora provides a small (but growing) collection of apps that can be installed.

The other main source of Flatpak apps is Flathub, which provides a large repository of Flatpak apps that can be installed.

Setting up Flathub

To setup Flathub on Fedora Sway Atomic, you can use the following command from the terminal:

$ flatpak remote-add --if-not-exists flathub

Installing Flatpak apps from Flathub

Once the Flathub repository has been setup, it can be used to install Flatpak apps.

Each application on can be installed through the terminal by running the installation command at the bottom of the page that should look something like this:

$ flatpak install flathub <package-name>

As an example, Firefox can be installed by running the following command which can be found on Firefox’s flathub page:

$ flatpak install flathub org.mozilla.firefox

Flatpak command line

Additional details about the flatpak command line interface can be found in the official Flatpak documentation.

Package layering

Package layering works by modifying your Fedora Sway Atomic installation. As the name implies, it works by extending the packages from which Fedora Sway Atomic is composed.

Good examples of packages to be layered would be:

  • fish: An alternative Unix shell

  • i3: A X11 tiling compositor

  • libvirt: The libvirt daemon

Most (but not all) RPM packages provided by Fedora can be installed on Fedora Sway Atomic using this method.

Currently, using package layering creates a new "deployment", or bootable filesystem root. It does not affect your current root. This preserves rollback and the transactional model, but means that the system must be rebooted after a package has been layered or updated. You can alternatively use rpm-ostree install --apply-live <pkg> to also temporarily apply the change directly to your currently booted deployment. It’s generally expected that you use package layering sparingly, and use flatpak and dnf install inside a toolbox etc.

Package layering is generally done from the command line. However, the Software application does rely on it for installing a small number of apps that are currently difficult to install as Flatpaks.

Installing packages

Packages can be installed on Fedora Sway Atomic using:

$ rpm-ostree install <package name>

This will download the package and any required dependencies, and recompose your Fedora Sway Atomic image with them. rpm-ostree uses standard Fedora package names, which can be searched with rpm-ostree search since Fedora Sway Atomic 39, or using DNF inside a toolbox for previous versions.

Once a package has been installed in this manner, it will be kept up-to-date as new versions are released and as the base operating system is updated.

Replacing packages

In some scenarios, you may want to test out a new version of podman or kernel or other packages that live on the host. The rpm-ostree override command can be used to replace a package with a different version. You can download the package locally and run:

$ rpm-ostree override replace <path to package>

Or you can override packages without downloading using links from koji or bodhi. For example:

$ rpm-ostree override replace

You may also use override remove to effectively "hide" packages; they will still exist in the underlying base layer, but will not appear in the booted root.

Removing and replacing packages using package layering is not generally recommended. For more information, see the rpm-ostree documentation.

Adding packages from external repositories