Once you have written an operating system declaration as seen in the
previous section, it can be instantiated using the
system command. The synopsis is:
guix system options… action file
file must be the name of a file containing an
declaration. action specifies how the operating system is
instantiated. Currently the following values are supported:
Display available service type definitions that match the given regular expressions, sorted by relevance:
$ guix system search console name: console-fonts location: gnu/services/base.scm:806:2 extends: shepherd-root description: Install the given fonts on the specified ttys (fonts are per + virtual console on GNU/Linux). The value of this service is a list of + tty/font pairs. The font can be the name of a font provided by the `kbd' + package or any valid argument to `setfont', as in this example: + + '(("tty1" . "LatGrkCyr-8x16") + ("tty2" . (file-append + font-tamzen + "/share/kbd/consolefonts/TamzenForPowerline10x20.psf")) + ("tty3" . (file-append + font-terminus + "/share/consolefonts/ter-132n"))) ; for HDPI relevance: 9 name: mingetty location: gnu/services/base.scm:1190:2 extends: shepherd-root description: Provide console login using the `mingetty' program. relevance: 2 name: login location: gnu/services/base.scm:860:2 extends: pam description: Provide a console log-in service as specified by its + configuration value, a `login-configuration' object. relevance: 2 …
guix package --search, the result is written in
recutils format, which makes it easy to filter the output
(see GNU recutils databases in GNU recutils manual).
Edit or view the definition of the given service types.
For example, the command below opens your editor, as specified by the
EDITOR environment variable, on the definition of the
guix system edit openssh
Build the operating system described in file, activate it, and switch to it33.
Nota: It is highly recommended to run
guix pullonce before you run
guix system reconfigurefor the first time (see Invocando
guix pull). Failing to do that you would see an older version of Guix once
This effects all the configuration specified in file: user accounts,
system services, global package list, setuid programs, etc. The command
starts system services specified in file that are not currently
running; if a service is currently running this command will arrange for it
to be upgraded the next time it is stopped (e.g. by
herd stop X or
herd restart X).
This command creates a new generation whose number is one greater than the
current generation (as reported by
guix system list-generations).
If that generation already exists, it will be overwritten. This behavior
mirrors that of
guix package (see Invocando
It also adds a bootloader menu entry for the new OS configuration, —unless --no-bootloader is passed. For GRUB, it moves entries for older configurations to a submenu, allowing you to choose an older system generation at boot time should you need it.
Upon completion, the new system is deployed under /run/current-system. This directory contains provenance meta-data: the list of channels in use (see Canais) and file itself, when available. You can view it by running:
guix system describe
This information is useful should you later want to inspect how this particular generation was built. In fact, assuming file is self-contained, you can later rebuild generation n of your operating system with:
guix time-machine \ -C /var/guix/profiles/system-n-link/channels.scm -- \ system reconfigure \ /var/guix/profiles/system-n-link/configuration.scm
You can think of it as some sort of built-in version control! Your system is
not just a binary artifact: it carries its own source. See
provenance-service-type, for more information on
reconfigure prevents you from downgrading your
system, which could (re)introduce security vulnerabilities and also cause
problems with “stateful” services such as database management systems.
You can override that behavior by passing --allow-downgrades.
Switch to an existing system generation. This action atomically switches the system profile to the specified system generation. It also rearranges the system’s existing bootloader menu entries. It makes the menu entry for the specified system generation the default, and it moves the entries for the other generations to a submenu, if supported by the bootloader being used. The next time the system boots, it will use the specified system generation.
The bootloader itself is not being reinstalled when using this command. Thus, the installed bootloader is used with an updated configuration file.
The target generation can be specified explicitly by its generation number. For example, the following invocation would switch to system generation 7:
guix system switch-generation 7
The target generation can also be specified relative to the current
generation with the form
+3 means “3
generations ahead of the current generation,” and
-1 means “1
generation prior to the current generation.” When specifying a negative
value such as
-1, you must precede it with
-- to prevent it
from being parsed as an option. For example:
guix system switch-generation -- -1
Currently, the effect of invoking this action is only to switch the
system profile to an existing generation and rearrange the bootloader menu
entries. To actually start using the target system generation, you must
reboot after running this action. In the future, it will be updated to do
the same things as
reconfigure, like activating and deactivating
This action will fail if the specified generation does not exist.
Switch to the preceding system generation. The next time the system boots,
it will use the preceding system generation. This is the inverse of
reconfigure, and it is exactly the same as invoking
switch-generation with an argument of
Currently, as with
switch-generation, you must reboot after
running this action to actually start using the preceding system generation.
Delete system generations, making them candidates for garbage collection
guix gc, for information on how to run the “garbage
This works in the same way as ‘guix package --delete-generations’ (see --delete-generations). With no arguments, all system generations but the current one are deleted:
guix system delete-generations
You can also select the generations you want to delete. The example below deletes all the system generations that are more than two months old:
guix system delete-generations 2m
Running this command automatically reinstalls the bootloader with an updated list of menu entries—e.g., the “old generations” sub-menu in GRUB no longer lists the generations that have been deleted.
Build the derivation of the operating system, 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 Guix 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 bootloader on the targets specified in my-os-config, unless the --no-bootloader option was passed.
Build a virtual machine (VM) that contains the operating system declared in file, and return a script to run that VM.
vmaction and others below can use KVM support in the Linux-libre kernel. Specifically, if the machine has 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 build users of the daemon (see Configuração do ambiente de compilação).
Arguments given to the script are passed to QEMU as in the example below, which enables networking and requests 1 GiB of RAM for the emulated machine:
$ /gnu/store/…-run-vm.sh -m 1024 -smp 2 -nic user,model=virtio-net-pci
It’s possible to combine the two steps into one:
$ $(guix system vm my-config.scm) -m 1024 -smp 2 -nic user,model=virtio-net-pci
The VM shares its store with the host system.
By default, the root file system of the VM is mounted volatile; the
--persistent option can be provided to make it persistent instead.
In that case, the VM disk-image file will be copied from the store to the
TMPDIR directory to make it writable.
Additional file systems can be shared between the host and the VM using the --share and --expose command-line options: the former specifies a directory to be shared with write access, while the latter provides read-only access to the shared directory.
The example below creates a VM in which the user’s home directory is accessible read-only, and where the /exchange directory is a read-write mapping of $HOME/tmp on the host:
guix system vm my-config.scm \ --expose=$HOME --share=$HOME/tmp=/exchange
On GNU/Linux, the default is to boot directly to the kernel; this has the advantage of requiring only a very tiny root disk image since the store of the host can then be mounted.
The --full-boot option forces a complete boot sequence, starting with the bootloader. This requires more disk space since a root image containing at least the kernel, initrd, and bootloader data files must be created.
The --image-size option can be used to specify the size of the image.
The --no-graphic option will instruct
guix system to
spawn a headless VM that will use the invoking tty for IO. Among other
things, this enables copy-pasting, and scrollback. Use the ctrl-a
prefix to issue QEMU commands; e.g. ctrl-a h prints a help,
ctrl-a x quits the VM, and ctrl-a c switches between the QEMU
monitor and the VM.
image command can produce various image types. The image type
can be selected using the --image-type option. It defaults to
efi-raw. When its value is
iso9660, the --label
option can be used to specify a volume ID with
image. By default,
the root file system of a disk image is mounted non-volatile; the
--volatile option can be provided to make it volatile instead.
image, the bootloader installed on the generated image is
taken from the provided
operating-system definition. The following
example demonstrates how to generate an image that uses the
grub-efi-bootloader bootloader and boot it with QEMU:
image=$(guix system image --image-type=qcow2 \ gnu/system/examples/lightweight-desktop.tmpl) cp $image /tmp/my-image.qcow2 chmod +w /tmp/my-image.qcow2 qemu-system-x86_64 -enable-kvm -hda /tmp/my-image.qcow2 -m 1000 \ -bios $(guix build ovmf)/share/firmware/ovmf_x64.bin
When using the
efi-raw image type, a raw disk image is produced; it
can be copied as is to a USB stick, for instance. Assuming
is the device corresponding to a USB stick, one can copy the image to it
using the following command:
# dd if=$(guix system image my-os.scm) of=/dev/sdc status=progress
--list-image-types command lists all the available image types.
When using the
qcow2 image type, the returned image is in qcow2
format, which the QEMU emulator can efficiently use. See Usando o Guix em uma Máquina Virtual, for more information on how to run the image in a virtual machine. The
grub-bootloader bootloader is always used independently of what is
declared in the
operating-system file passed as argument. This is to
make it easier to work with QEMU, which uses the SeaBIOS BIOS by default,
expecting a bootloader to be installed in the Master Boot Record (MBR).
When using the
docker image type, a Docker image is produced. Guix
builds the image from scratch, not from a pre-existing Docker base image.
As a result, it contains exactly what you define in the operating
system configuration file. You can then load the image and launch a Docker
container using commands like the following:
image_id="$(docker load < guix-system-docker-image.tar.gz)" container_id="$(docker create $image_id)" docker start $container_id
This command starts a new Docker container from the specified image. It
will boot the Guix system in the usual manner, which means it will start any
services you have defined in the operating system configuration. You can
get an interactive shell running in the container using
docker exec -ti $container_id /run/current-system/profile/bin/bash --login
Depending on what you run in the Docker container, it may be necessary to
give the container additional permissions. For example, if you intend to
build software using Guix inside of the Docker container, you may need to
pass the --privileged option to
Last, the --network option applies to
docker-image: it produces an image where network is supposedly shared with
the host, and thus without services like nscd or NetworkManager.
Return a script to run the operating system declared in file within a container. Containers are a set of lightweight isolation mechanisms provided by the kernel Linux-libre. Containers are substantially less resource-demanding than full virtual machines since the kernel, shared objects, and other resources can be shared with the host system; this also means they provide thinner isolation.
Currently, the script must be run as root in order to support more than a single user and group. The container shares its store with the host system.
As with the
vm action (see guix system vm), additional file
systems to be shared between the host and container can be specified using
the --share and --expose options:
guix system container my-config.scm \ --expose=$HOME --share=$HOME/tmp=/exchange
The --share and --expose options can also be passed to the generated script to bind-mount additional directories into the container.
Nota: This option requires Linux-libre 3.19 or newer.
options can contain any of the common build options (see Opções de compilação comum). In addition, options can contain one of the following:
Consider the operating-system expr evaluates to. This is an alternative to specifying a file which evaluates to an operating system. This is used to generate the Guix system installer see Compilando a imagem de instalação).
Attempt to build for system instead of the host system type. This
works as per
guix build (see Invocando
Cross-build for triplet, which must be a valid GNU triplet, such as
"aarch64-linux-gnu" (see GNU
configuration triplets in Autoconf).
Return the derivation file name of the given operating system without building anything.
As discussed above,
guix system init and
reconfigure always save provenance information via a dedicated service
provenance-service-type). However, other
commands don’t do that by default. If you wish to, say, create a virtual
machine image that contains provenance information, you can run:
guix system image -t qcow2 --save-provenance config.scm
That way, the resulting image will effectively “embed its own source” in the form of meta-data in /run/current-system. With that information, one can rebuild the image to make sure it really contains what it pretends to contain; or they could use that to derive a variant of the image.
image action, create an image with given type.
When this option is omitted,
guix system uses the
--image-type=iso9660 produces an ISO-9660 image, suitable for burning on CDs and DVDs.
image action, create an image of the given size.
size may be a number of bytes, or it may include a unit as a suffix
(see size specifications in GNU Coreutils).
When this option is omitted,
guix system computes an estimate of
the image size as a function of the size of the system declared in
container action, allow containers to access the host
network, that is, do not create a network namespace.
Make file a symlink to the result, and register it as a garbage collector root.
Skip pre-installation safety checks.
guix system init and
guix system reconfigure
perform safety checks: they make sure the file systems that appear in the
operating-system declaration actually exist (see Sistemas de arquivos),
and that any Linux kernel modules that may be needed at boot time are listed
initrd-modules (see Disco de RAM inicial). Passing this option
skips these tests altogether.
guix system reconfigure to allow system downgrades.
reconfigure prevents you from downgrading your
system. It achieves that by comparing the provenance info of your system
guix system describe) with that of your
command (shown by
guix describe). If the commits for
guix are not descendants of those used for your system,
guix system reconfigure errors out. Passing
--allow-downgrades allows you to bypass these checks.
Nota: Make sure you understand its security implications before using --allow-downgrades.
Apply strategy when an error occurs when reading file. strategy may be one of the following:
Report the error concisely and exit. This is the default strategy.
Likewise, but also display a backtrace.
Report the error and enter Guile’s debugger. From there, you can run
commands such as
,bt to get a backtrace,
,locals to display
local variable values, and more generally inspect the state of the program.
See Debug Commands in GNU Guile Reference Manual, for a list of
available debugging commands.
Once you have built, configured, re-configured, and re-re-configured your Guix installation, you may find it useful to list the operating system generations available on disk—and that you can choose from the bootloader boot menu:
Describe the running system generation: its file name, the kernel and bootloader used, etc., as well as provenance information when available.
--list-installed flag is available, with the same syntax that is
guix package --list-installed (see Invocando
guix package). When the flag is used, the description will include a list of
packages that are currently installed in the system profile, with optional
filtering based on a regular expression.
Nota: The running system generation—referred to by /run/current-system—is not necessarily the current system generation—referred to by /var/guix/profiles/system: it differs when, for instance, you chose from the bootloader menu to boot an older generation.
It can also differ from the booted system generation—referred to by /run/booted-system—for instance because you reconfigured the system in the meantime.
List a summary of each generation of the operating system available on disk,
in a human-readable way. This is similar to the --list-generations
guix package (see Invocando
Optionally, one can specify a pattern, with the same syntax that is used in
guix package --list-generations, to restrict the list of
generations displayed. For instance, the following command displays
generations that are up to 10 days old:
$ guix system list-generations 10d
--list-installed flag may also be specified, with the same syntax
that is used in
guix package --list-installed. This may be
helpful if trying to determine when a package was added to the system.
guix system command has even more to offer! The following
sub-commands allow you to visualize how your system services relate to each
Emit to standard output the service extension graph of the operating
system defined in file (see Composição de serviço, for more
information on service extensions). By default the output is in
Dot/Graphviz format, but you can choose a different format with
--graph-backend, as with
guix graph (see --backend):
$ guix system extension-graph file | xdot -
shows the extension relations among services.
dotprogram is provided by the
Emit to standard output the dependency graph of shepherd services of the operating system defined in file. See Serviços de Shepherd, for more information and for an example graph.
Again, the default output format is Dot/Graphviz, but you can pass --graph-backend to select a different one.
This action (and the related actions
roll-back) are usable only on systems already running Guix