In this article
NixOS lets you describe much of your system in configuration: which programs exist, which services run and how the desktop is set up. My configuration.nix in the Cthulhu repository provides a concrete example. The long file consists of many small decisions that you can understand separately.
This introduction assumes that you already have a working NixOS installation. By the end, you should be able to identify the main blocks and test one package change. The examples refer to the published file reviewed on 7 October 2026. It describes Cthulhu with Plasma and Radeon graphics; another computer needs its own hardware settings.
How do you read configuration.nix?
The file is a NixOS module. Its opening receives values including pkgs, which provides access to packages. The attribute set that follows contains settings. A small excerpt looks like this:
{ config, pkgs, ... }:
{
imports = [ ./hardware-configuration.nix ];
networking.networkmanager.enable = true;
time.timeZone = "Europe/Berlin";
}Braces group attributes; square brackets contain a list. Strings have quotation marks, and Boolean values are true and false. Assignments end in semicolons. A dot in an option name takes you into a nested setting.
imports connects other modules to this file. The hardware file contains details such as detected filesystems and modules needed by this machine. Keep your own hardware file when learning. Add examples inside your existing configuration rather than replacing its hardware foundation with mine.
Installing packages and enabling services
Everyday applications appear in environment.systemPackages. With with pkgs;, their names do not need a repeated pkgs. prefix. This excerpt deliberately shortens my list:
environment.systemPackages = with pkgs; [
kitty
curl
git
tree
];This makes the programs available system-wide. A background service needs more: it has to be configured and started. Appropriate NixOS modules handle that, as with networking.networkmanager.enable = true;. Adding a package name therefore does not replace configuring its service.
Applications can also have dedicated modules. My file uses programs.firefox.enable = true;. Look up a setting in the NixOS option search with the appropriate NixOS release selected. An example found elsewhere may use an option path that has since changed.
What do Plasma and PipeWire configure?
My configuration enables SDDM for login and Plasma 6 for the desktop. The key settings are:
services.displayManager.sddm.enable = true;
services.desktopManager.plasma6.enable = true;Xserver support and a German XKB keyboard layout are configured separately. Their presence does not mean every Plasma session runs on X11. The desktop environment, display manager and session type are different parts of the setup.
For audio, the file enables PipeWire, WirePlumber and ALSA/PulseAudio compatibility. The separate PulseAudio service is disabled. Applications using a PulseAudio interface can still play audio. When something fails, first identify which audio path is active; competing services make the setup harder to understand.
Which parts depend on my computer?
| Block in my file | What you can learn from it |
|---|---|
User nebu and groups | A normal user account with deliberate permissions; adapt the name and groups. |
| Timezone, locale and keyboard | The distinction between language, console keyboard and graphical keyboard layout. |
| Radeon graphics and 32-bit support | The purpose of the options; check your own graphics driver separately. |
Mounts under /mnt | How filesystems are described; these labels and mount points belong to my drives. |
KVM, libvirt and virbr0 | The relationship to virtual machines; use the network rule only with a corresponding setup. |
The file also selects a current kernel, ZRAM and personal boot settings. These choices are not prerequisites for using NixOS. Start with your working system and change one area at a time. That keeps the connection between an edit and its result visible.
A small exercise: Add jq
Our example adds jq, a command-line JSON processor. First save your current main file. This command keeps a numbered copy of any existing backup destination:
sudo cp -a --backup=numbered /etc/nixos/configuration.nix /etc/nixos/configuration.nix.before-tutorialBack up other imported files too if you will edit them. Open your configuration in an editor and add jq to the existing package list. The excerpt is shortened: keep your other package names. Avoid creating a second assignment to the same option.
environment.systemPackages = with pkgs; [
kitty
curl
git
tree
jq
];The following commands fit a traditional local configuration. If your system uses flakes, keep its existing rebuild invocation and appropriate --flake target. Build first without activating the result:
sudo nixos-rebuild buildA successful build establishes that evaluation and construction completed. It does not replace checking actual behaviour. Next, test the configuration in the running session:
sudo nixos-rebuild testtest activates changes without making them the new boot default. Services can change during activation. Check the added application:
jq --versionIf a version number appears and the rest of the system behaves as expected, make the configuration the new persistent system generation:
sudo nixos-rebuild switchHow do you undo the change?
For this exercise, remove jq from the list and rebuild. Alternatively, restore your saved file if no later edits need to be preserved:
sudo cp -a /etc/nixos/configuration.nix.before-tutorial /etc/nixos/configuration.nixAfter copying back the file, build and activate it again with sudo nixos-rebuild switch. As an alternative to that rebuild, after a previously committed switch you can activate the previous system generation if it still exists:
sudo nixos-rebuild switch --rollbackA rollback does not revert your edited source file or restore personal documents. A later rebuild uses the configuration on disk again. After a plain test, the previous boot default remains; rebooting normally returns to it. There is no automatic rollback during the running session.
Privacy, generations and stateVersion
Configuration files are local text, but may contain usernames, disk labels and network details. Nix places many evaluated contents into the Nix store, which is commonly readable locally. Passwords, private keys and access tokens should therefore not appear in plain text in these examples or a public repository.
system.stateVersion does not select the latest package release. It influences compatibility defaults for persistent system state. Keep the deliberately chosen value for your installation rather than copying my 26.05. Generations help you return to a system configuration; they do not replace data backups. Continue with the configuration backup guide for that distinction.
Configuration and further reading
This guide is based on the published Cthulhu file and NixOS documentation, reviewed on 7 October 2026. The exercise deliberately adds one package; it is not a complete replacement for your system configuration.