An Example Configuration

Here's a configuration for a simple desktop system:

;; This is a Guix System configuration file.
;; It describes an entire operating system.

(use-modules (gnu)
             (gnu packages emacs)
             (gnu packages vim)
             (gnu packages version-control)
             (gnu packages web-browsers)
             (gnu packages terminals)
             (gnu services desktop))

(operating-system
  ;; Basic system identity
  (host-name "guix-desktop")
  (timezone "America/New_York")
  (locale "en_US.utf8")

  ;; Keyboard layout
  (keyboard-layout (keyboard-layout "us"))

  ;; User accounts
  (users (cons* (user-account
                  (name "alice")
                  (group "users")
                  (home-directory "/home/alice")
                  (supplementary-groups '("wheel"   ; Allow sudo
                                          "audio"
                                          "video")))
                %base-user-accounts))

  ;; Packages available system-wide
  (packages (append (list emacs
                          vim
                          git
                          firefox
                          alacritty)
                    %base-packages))

  ;; System services
  (services (append (list
                      ;; Graphical desktop
                      (service gnome-desktop-service-type)
                      ;; Enable SSH access
                      (service openssh-service-type))
                    %desktop-services))

  ;; Bootloader configuration
  (bootloader (bootloader-configuration
                (bootloader grub-efi-bootloader)
                (targets (list "/boot/efi"))))

  ;; File systems (simplified example)
  (file-systems (cons* (file-system
                         (mount-point "/")
                         (device "/dev/sda2")
                         (type "ext4"))
                       (file-system
                         (mount-point "/boot/efi")
                         (device "/dev/sda1")
                         (type "vfat"))
                       %base-file-systems)))

Let's walk through the major sections:

(host-name "guix-desktop")
(timezone "America/New_York")
(locale "en_US.utf8")

These set the machine's name, timezone, and language settings. We'll cover how to find the right values for your location during the installation walkthrough.

(users (cons* (user-account
                (name "alice")
                (group "users")
                (supplementary-groups '("wheel"
                                        "audio"
                                        "video")))
              %base-user-accounts))

This creates a user named "alice" who can use sudo (via the "wheel" group) and access audio/video devices. The cons* and %base-user-accounts syntax adds our user to Guix's default system users. We'll explain this pattern shortly.

(packages (append (list emacs
                        vim
                        git
                        ...)
                  %base-packages))

The packages section lists software available to all users on the system. Notice that we reference packages like emacs and git directly by name. This works because we imported their modules at the top of the file (like (gnu packages emacs)). We're appending our packages to %base-packages, which includes essential tools Guix needs to function.

(services (append (list
                    (service gnome-desktop-service-type)
                    (service openssh-service-type))
                  %desktop-services))

Services are background processes and system configurations. Here we're adding GNOME and SSH to the default desktop services which already includes things like networking, printing, and power management.

(bootloader (bootloader-configuration
              (bootloader grub-efi-bootloader)
              (targets (list "/boot/efi"))))

(file-systems (cons* (file-system
                       (mount-point "/")
                       (device "/dev/sda2")
                       (type "ext4"))
                     ...))

These sections configure how the system boots and where file systems are mounted. The standard Guix installer generates these based on your hardware.

From this single file, Guix will build:

• A bootable Linux system with the Linux kernel
• The GNOME desktop environment
• The five applications we listed (Emacs, Vim, Git, Firefox, Alacritty)
• A user account for Alice with appropriate permissions
• An SSH server for remote access
• All the supporting infrastructure (networking, audio, power management, etc.)

And here's the important part: this is the complete specification. There are no hidden steps, no "oh, I also had to manually edit this config file" moments.

Another person with this same file would get an identical system as long as their hard drive was partitioned the same way with the same device names.

Notice how we keep using this pattern:

(append (list our-stuff ...) %base-stuff)

This is idiomatic Guix. The %base-packages, %base-services, and %desktop-services variables contain sensible defaults. We add our customizations to these lists rather than starting from scratch.

You can also remove things from these base lists, or replace them entirely if you want fine-grained control. But for most users, extending the defaults is the right approach.

To understand this configuration fully, you'll need to learn a bit of Scheme, the programming language Guix configurations are written in. Don't worry: you don't need to become a Scheme programmer! You just need to recognize a few patterns.