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.2, the Guix System Distribution (GuixSD) 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 GuixSD 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.2:

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 guixsd-usb-install-0.8.2.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=guixsd-usb-install-0.8.2.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 eno1 (to get an automatically assigned IP address from the wired network interface controller11), 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.

See Using the Configuration System, for examples of operating system configurations. These examples are available under /etc/configuration in the installation image, so you can copy them and use them as a starting point for your own configuration.

Once you are done preparing the configuration file, 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.



The name eno1 is for the first on-board Ethernet controller. The interface name for an Ethernet controller that is in the first slot of the first PCI bus, for instance, would be enp1s0. Use ifconfig -a to list all the available network interfaces.

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