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.
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.
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:
xz -d guixsd-usb-install-0.8.2.system.xz
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.
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:
dhclient eno1(to get an automatically assigned IP address from the wired network interface controller11), or using the
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.
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.
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.
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
reboot and boot into the new system. Cross fingers, and
join us on
#guix on the Freenode IRC network or on
firstname.lastname@example.org to share your experience—good or not so
The installation image described above was built using the
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.
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
ifconfig -a to list all the available network interfaces.