Next: , Up: GNU Distribution   [Contents][Index]

6.1 System Installation

This section explains how to install the Guix System Distribution on a machine. The Guix package manager can also be installed on top of a running GNU/Linux system, see Installation.

6.1.1 Limitations

As of version 0.8.1, the Guix System Distribution (GSD) is not production-ready. It may contain bugs and lack important features. Thus, if you are looking for a stable production system that respects your freedom as a computer user, a good solution at this point is to consider one of more established GNU/Linux distributions. We hope you can soon switch to the GSD without fear, of course. In the meantime, you can also keep using your distribution and try out the package manager on top of it (see Installation).

Before you proceed with the installation, be aware of the following noteworthy limitations applicable to version 0.8.1:

You’ve been warned. But more than a disclaimer, this is an invitation to report issues (and success stories!), and join us in improving it. See Contributing, for more info.

6.1.2 USB Stick Installation

An installation image for USB sticks can be downloaded from, where system is one of:


for a GNU/Linux system on Intel/AMD-compatible 64-bit CPUs;


for a 32-bit GNU/Linux system on Intel-compatible CPUs.

This image contains a single partition with the tools necessary for an installation. It is meant to be copied as is to a large-enough USB stick.

To copy the image to a USB stick, follow these steps:

  1. Decompress the image using the xz command:
    xz -d gsd-usb-install-0.8.1.system.xz
  2. Insert a USB stick of 1 GiB or more in your machine, and determine its device name. Assuming that USB stick is known as /dev/sdX, copy the image with:
    dd if=gsd-usb-install-0.8.1.x86_64 of=/dev/sdX

    Access to /dev/sdX usually requires root privileges.

Once this is done, you should be able to reboot the system and boot from the USB stick. The latter usually requires you to get in the BIOS’ boot menu, where you can choose to boot from the USB stick.

6.1.3 Preparing for Installation

Once you have successfully booted the image on the USB stick, you should end up with a root prompt. Several console TTYs are configured and can be used to run commands as root. TTY2 shows this documentation, browsable using the Info reader commands (see Help in Info: An Introduction).

To install the system, you would:

  1. Configure the network, by running dhclient eth0 (to get an automatically assigned IP address from the wired network interface controller), or using the ifconfig command.

    The system automatically loads drivers for your network interface controllers.

    Setting up network access is almost always a requirement because the image does not contain all the software and tools that may be needed.

  2. Unless this has already been done, you must partition and format the target partitions.

    Preferably, assign partitions a label so that you can easily and reliably refer to them in file-system declarations (see File Systems). This is typically done using the -L option of mkfs.ext4 and related commands.

    The installation image includes Parted (see Overview in GNU Parted User Manual), fdisk, Cryptsetup/LUKS for disk encryption, and e2fsprogs, the suite of tools to manipulate ext2/ext3/ext4 file systems.

  3. Once that is done, mount the target root partition under /mnt.
  4. Lastly, run deco start cow-store /mnt.

    This will make /gnu/store copy-on-write, such that packages added to it during the installation phase will be written to the target disk rather than kept in memory.

6.1.4 Proceeding with the Installation

With the target partitions ready, you now have to edit a file and provide the declaration of the operating system to be installed. To that end, the installation system comes with two text editors: GNU nano (see GNU nano Manual), and GNU Zile, an Emacs clone. It is better to store that file on the target root file system, say, as /mnt/etc/config.scm.

A minimal operating system configuration, with just the bare minimum and only a root account would look like this (on the installation system, this example is available as /etc/configuration-template.scm):

;; This is an operating system configuration template.

(use-modules (gnu))
(use-service-modules xorg networking dbus avahi)
(use-package-modules avahi)

  (host-name "antelope")
  (timezone "Europe/Paris")
  (locale "en_US.UTF-8")

  ;; Assuming /dev/sdX is the target hard disk, and "root" is
  ;; the label of the target root file system.
  (bootloader (grub-configuration (device "/dev/sdX")))
  (file-systems (cons (file-system
                        (device "root")
                        (title 'label)
                        (mount-point "/")
                        (type "ext4"))

  ;; This is where user accounts are specified.  The "root"
  ;; account is implicit, and is initially created with the
  ;; empty password.
  (users (list (user-account
                (name "alice")
                (comment "Bob's sister")
                (group "users")

                ;; Adding the account to the "wheel" group
                ;; makes it a sudoer.  Adding it to "audio"
                ;; and "video" allows the user to play sound
                ;; and access the webcam.
                (supplementary-groups '("wheel"
                                        "audio" "video"))
                (home-directory "/home/alice"))))

  ;; Add services to the baseline: the SLiM log-in manager
  ;; for Xorg sessions, a DHCP client, Avahi, and D-Bus.
  (services (cons* (slim-service)
                   (dbus-service (list avahi))

For more information on operating-system declarations, see Using the Configuration System.

Once that is done, the new system must be initialized (remember that the target root file system is mounted under /mnt):

guix system init /mnt/etc/config.scm /mnt

This will copy all the necessary files, and install GRUB on /dev/sdX, unless you pass the --no-grub option. For more information, see Invoking guix system. This command may trigger downloads or builds of missing packages, which can take some time.

Once that command has completed—and hopefully succeeded!—you can run reboot and boot into the new system. Cross fingers, and join us on #guix on the Freenode IRC network or on to share your experience—good or not so good.

6.1.5 Building the Installation Image

The installation image described above was built using the guix system command, specifically:

guix system disk-image --image-size=850MiB gnu/system/install.scm

See Invoking guix system, for more information. See gnu/system/install.scm in the source tree for more information about the installation image.

Next: , Up: GNU Distribution   [Contents][Index]