GLF OS gives you two ways to add a program that is not installed by default. You can declare a NixOS package in your personal configuration, which the system then builds and integrates, or install a Flatpak application, in a few clicks with EasyFlatpak or from the command line. This page helps you choose the right method, then guides you step by step.

Which method should you choose?

Flatpak (EasyFlatpak) NixOS package
Installation Immediate, from a graphical software store or a command One line to add to a configuration file, then a command to apply it
Reboot Never needed Needed with glf-update; glf-switch applies without rebooting
Catalog Flathub, mainly desktop applications The NixOS package catalog: desktop applications, but also command-line tools and software that integrates with the system
Isolation Applications isolated in a sandbox The program is part of the system, with no sandbox
Updates Updated by glf-update along with the system Updated with the system sources, during glf-update or glf-switch
Best for Browsers, messaging apps, creative software and, more broadly, common desktop applications Command-line tools, software not available on Flathub, software that needs permissions or services on the system

Tip

If in doubt about a desktop application, start with EasyFlatpak: installation is immediate, requires no reboot and does not touch the system configuration. Keep NixOS packages for cases where Flatpak is not suitable.

Configuration files

The GLF OS configuration is located in the /etc/nixos folder. Several files live there side by side, but only the customConfig folder is reserved for you.

File Role Edit?
customConfig/default.nix Your personal file for all your additions (programs, options). It is never touched by the GLF tools. Yes
Your .nix files in customConfig/ Files you create yourself to organize your additions. They belong to you. Yes
configuration.nix Generated by the installer (boot, users and passwords, language, keyboard, GLF edition) and automatically corrected by glf-update as the system evolves. It imports hardware-configuration.nix and customConfig. Never
hardware-configuration.nix Detection of your hardware, generated during installation. Never
customized.nix Managed by the GLF Customizer application, which automatically rewrites its tagged section. Use GLF Customizer to change these settings. Never
flake.nix and flake.lock Managed by glf-update: stable or testing channel, format migrations, source versions. Never

Caution

Do not edit the files marked "Never". Your changes may be overwritten by the GLF tools, or may block your system updates. Every program or option you add goes through the customConfig folder.

Adding a NixOS package

1. Find the package

Each NixOS package has a specific name that you will need to copy exactly into your configuration. Two channels are available to you:

Syntax Channel Characteristics
pkgs.<name> Stable (currently NixOS 26.05) Well-tested versions, to use by default
pkgs-unstable.<name> nixos-unstable Newer versions, but less tested

The nixos-version command displays the NixOS version installed on your computer. Non-free software is allowed on both channels: for example, you can install Google Chrome with pkgs.google-chrome.

On the search website

  1. Open search.nixos.org.
  2. Choose the channel: 26.05 if you plan to use pkgs, unstable if you plan to use pkgs-unstable.
  3. Type the name of the software, for example qbittorrent. You can also open the address https://search.nixos.org/packages?channel=26.05&query=qbittorrent directly.
  4. Click the package to expand its details, then click the NixOS Configuration tab: it shows the exact line to copy, for example pkgs.qbittorrent (the bold title of the result also gives the full name).

Warning

This tab says the configuration is "usually located in /etc/nixos/configuration.nix". On GLF OS, do not touch that file: only copy the pkgs.qbittorrent line into customConfig/default.nix, as explained in the next step.

Versions often differ from one channel to another. For example, qBittorrent is available in version 5.2.2 on the 26.05 channel and in version 5.2.3 on unstable.

Some names contain a dot, such as kdePackages.filelight. Copy them as they are, preceded by the channel: pkgs.kdePackages.filelight. For these packages, the "Name" line only shows the end of the name ("filelight"), which is why the NixOS Configuration tab is useful.

From the command line

nix search nixpkgs qbittorrent

For each result, the command displays the attribute name, the version and a description. The first run may take a while.

Try a program without installing it

Before changing your configuration, you can test a piece of software:

nix shell nixpkgs#qbittorrent

Then run qbittorrent from that same terminal. Nothing is permanently installed on your system.

Note

Some software has a dedicated NixOS option, visible in the "Options" tab of search.nixos.org. This option also sets up the permissions and services the software needs: when it exists, prefer it over the plain package. For example, for Wireshark, add the line programs.wireshark.enable = true; under the # Add your custom configuration here ↓ comment in customConfig/default.nix.

2. Declare the package in customConfig/default.nix

Open the file

The files in /etc/nixos belong to the administrator (root). To edit them, open a terminal and type:

sudo nano /etc/nixos/customConfig/default.nix

Enter your password. In the nano editor, save with Ctrl+O then Enter, and exit with Ctrl+X.

You can also use your desktop's graphical text editor: you will be asked for your password when you save.

Add the package to the list

Find the environment.systemPackages list. On a fresh installation, it only contains two comments:

  environment.systemPackages = [
    # Add your stable apps here (exemple: pkgs.btop)

    # Add your unstable apps here (exemple: pkgs-unstable.btop)

  ];

Add your stable packages under the first comment, and your unstable packages under the second. Here is the same list after adding qBittorrent and KeePassXC from the stable channel, and FreeCAD from the unstable channel:

  environment.systemPackages = [
    # Add your stable apps here (exemple: pkgs.btop)
    pkgs.qbittorrent
    pkgs.keepassxc

    # Add your unstable apps here (exemple: pkgs-unstable.btop)
    pkgs-unstable.freecad

  ];

Save the file. The program is not installed yet: you still need to apply the configuration (step 4).

Syntax rules to follow

Warning

Do not modify the file header, that is, the { lib, config, pkgs, pkgs-unstable, ... }: block at the very top. Without it, the system no longer knows what pkgs and pkgs-unstable mean, and the build fails.

3. Alternative: keep your programs in a separate file

If your list grows longer, you can split your programs across several files, for example by theme. These files belong to you, just like default.nix.

Create the file

sudo nano /etc/nixos/customConfig/mes-programmes.nix

Write the following content in it, adapting the list of packages:

{ pkgs, pkgs-unstable, ... }:

{
  environment.systemPackages = [
    pkgs.krita
    pkgs-unstable.inkscape
  ];
}

The first line is the header of this file. If you use pkgs-unstable packages, it must include pkgs-unstable.

Import the file in default.nix

Open customConfig/default.nix and add an imports line right after the opening brace that follows }::

{
  lib,
  config,
  pkgs,
  pkgs-unstable,
  ...
}:

{
  imports = [ ./mes-programmes.nix ];

  environment.systemPackages = [
    # Add your stable apps here (exemple: pkgs.btop)

A few details:

4. Apply the configuration

Saving the file is not enough: you then need to ask the system to build the new configuration. Three commands are available.

glf-update (recommended method)

glf-update

This command:

Once the command has finished, restart your computer: your new programs are then available.

glf-switch: apply without rebooting

glf-switch

This command also updates the sources, then applies the configuration immediately, without a reboot. It then deletes generations older than 5 days. Some changes still require a reboot to take effect.

glf-build: check without applying anything

glf-build

This command builds the configuration without applying anything. It is handy for checking that your files contain no errors.

Note

Don't worry if something goes wrong: if the build fails, for example because of a typo in a file, nothing is installed and your current system stays unchanged. Fix the file (see the "Troubleshooting" section below) then run the command again. In addition, the previous generations of your system remain available in the boot menu: you can always go back.

5. Remove a program

To remove a program added this way, delete its line from the file, or turn it into a comment by adding # in front of it:

    # pkgs.qbittorrent

Then apply the configuration as you would for an addition: glf-update followed by a reboot, or glf-switch.

Installing a Flatpak application

Flatpak is enabled on GLF OS and the Flathub repository is added automatically: there is nothing for you to configure. Flatpak applications install immediately, without a reboot, run isolated in a sandbox and are often available in recent versions.

With EasyFlatpak

EasyFlatpak is a graphical software store preinstalled with GLF OS. You will find it in the applications menu (in the "GLF Apps" folder on GNOME).

  1. Open EasyFlatpak, then type the name of the application in the Search… field or browse the Categories.
  2. Open the application's page and click Install.
  3. In the window that opens, turn Install for current user only on or off, then confirm with Install.

The installation continues in the background: the Pending section lets you follow its progress.

EasyFlatpak also offers:

For an illustrated tour of the application, see the Easy Flatpak guide (in French).

From the command line

Flatpak applications are identified by an ID, for example org.qbittorrent.qBittorrent for qBittorrent. Find it in the search results, then use it in the other commands:

# Search for an application
flatpak search qbittorrent

# Install the application from Flathub
flatpak install flathub org.qbittorrent.qBittorrent

# Run the application
flatpak run org.qbittorrent.qBittorrent

# List installed applications
flatpak list --app

# Uninstall the application
flatpak uninstall org.qbittorrent.qBittorrent

# Remove components no longer used by any application
flatpak uninstall --unused

To install an application for the current user only, add the --user option:

flatpak install --user flathub org.qbittorrent.qBittorrent

Your Flatpak applications are updated on every glf-update. If you prefer to manage these updates yourself, uncomment the line # glf.autoUpgrade.flatpak.enable = false; (remove the # at the start of the line) in customConfig/default.nix; if it is missing, add glf.autoUpgrade.flatpak.enable = false; under the # Add your custom configuration here ↓ comment. For the other options in this block, see Modularity (in French).

Tip

To adjust the permissions of your Flatpak applications, install Flatseal from Flathub (ID com.github.tchx84.Flatseal), with EasyFlatpak or with the command flatpak install flathub com.github.tchx84.Flatseal.

Troubleshooting

Here are the most common error messages when adding a NixOS package, and how to fix them.

If a problem occurs after rebooting, choose a previous generation in the boot menu to get your system back as it was, then fix your configuration.

See also