This section explains how to install the complete GNU operating system 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, GNU Guix and the GNU system distribution are alpha software. 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 GNU system 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:
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 ftp://alpha.gnu.org/gnu/guix/gnu-usb-install-0.8.system.xz, 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 gnu-usb-install-0.8.system.xz
dd if=gnu-usb-install-0.8.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 eth0(to get an automatically assigned IP address from the wired network interface controller), 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, 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.
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)) (operating-system (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")) %base-file-systems)) ;; 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")))))
For more information on
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
reboot and boot into the new system. Cross fingers, and
join us on
#guix on the Freenode IRC network or on
email@example.com 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=800MiB 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.