7.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.

7.1.1 Limitations

As of version 0.9.0, 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.9.0:

• The installation process does not include a graphical user interface and requires familiarity with GNU/Linux (see the following subsections to get a feel of what that means.)
• The system does not yet provide full GNOME and KDE desktops. Xfce and Enlightenment are available though, if graphical desktop environments are your thing, as well as a number of X11 window managers.
• Support for the Logical Volume Manager (LVM) is missing.
• Few system services are currently supported out-of-the-box (see Services).
• More than 2,000 packages are available, but you may occasionally find that a useful package is missing.

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.

7.1.2 USB Stick Installation

An installation image for USB sticks can be downloaded from ‘ftp://alpha.gnu.org/gnu/guix/guixsd-usb-install-0.9.0.system.xz’, where system is one of:

x86_64-linux

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

i686-linux

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.9.0.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.9.0.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.

7.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 ifconfig eno1 up && dhclient eno1 (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 then format the target partition.

   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.

7.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. The root password in the new system is initially empty; other users’ passwords need to be initialized by running the passwd command as root, unless your configuration specifies otherwise (see user account passwords).

Join us on #guix on the Freenode IRC network or on guix-devel@gnu.org to share your experience—good or not so good.

7.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.