Next: , Previous: , Up: System Configuration   [Contents][Index]

6.2.7 Invoking guix system

Once you have written an operating system declaration, as seen in the previous section, it can be instantiated using the guix system command. The synopsis is:

guix system optionsaction file

file must be the name of a file containing an operating-system declaration. action specifies how the operating system is instantiate. Currently the following values are supported:


Build the operating system described in file, activate it, and switch to it10.

This effects all the configuration specified in file: user accounts, system services, global package list, setuid programs, etc.

It also adds a GRUB menu entry for the new OS configuration, and moves entries for older configurations to a submenu—unless --no-grub is passed.


Build the operating system’s derivation, which includes all the configuration files and programs needed to boot and run the system. This action does not actually install anything.


Populate the given directory with all the files necessary to run the operating system specified in file. This is useful for first-time installations of the GNU system. For instance:

guix system init my-os-config.scm /mnt

copies to /mnt all the store items required by the configuration specified in my-os-config.scm. This includes configuration files, packages, and so on. It also creates other essential files needed for the system to operate correctly—e.g., the /etc, /var, and /run directories, and the /bin/sh file.

This command also installs GRUB on the device specified in my-os-config, unless the --no-grub option was passed.


Build a virtual machine that contain the operating system declared in file, and return a script to run that virtual machine (VM).

The VM shares its store with the host system.


Return a virtual machine or disk image of the operating system declared in file that stands alone. Use the --image-size option to specify the size of the image.

When using vm-image, the returned image is in qcow2 format, which the QEMU emulator can efficiently use.

When using disk-image, a raw disk image is produced; it can be copied as is to a USB stick, for instance. Assuming /dev/sdc is the device corresponding to a USB stick, one can copy the image on it using the following command:

# dd if=$(guix system disk-image my-os.scm) of=/dev/sdc

options can contain any of the common build options provided by guix build (see Invoking guix build). In addition, options can contain one of the following:

-s system

Attempt to build for system instead of the host’s system type. This works as per guix build (see Invoking guix build).


For the vm-image and disk-image actions, create an image of the given size. size may be a number of bytes, or it may include a unit as a suffix, such as MiB for mebibytes and GB for gigabytes.

Note that all the actions above, except build and init, rely on KVM support in the Linux-Libre kernel. Specifically, the machine should have hardware virtualization support, the corresponding KVM kernel module should be loaded, and the /dev/kvm device node must exist and be readable and writable by the user and by the daemon’s build users.



This action is usable only on systems already running GNU.

Next: , Previous: , Up: System Configuration   [Contents][Index]