7.1 Invoking guix shell

The purpose of guix shell is to make it easy to create one-off software environments, without changing one’s profile. It is typically used to create development environments; it is also a convenient way to run applications without “polluting” your profile.

Nota: The guix shell command was recently introduced to supersede guix environment (see Invocación de guix environment). If you are familiar with guix environment, you will notice that it is similar but also—we hope!—more convenient.

La sintaxis general es:

guix shell [options] [package…]

The following example creates an environment containing Python and NumPy, building or downloading any missing package, and runs the python3 command in that environment:

guix shell python python-numpy -- python3

Note that it is necessary to include the main python package in this command even if it is already installed into your environment. This is so that the shell environment knows to set PYTHONPATH and other related variables. The shell environment cannot check the previously installed environment, because then it would be non-deterministic. This is true for most libraries: their corresponding language package should be included in the shell invocation.

Nota: guix shell can be also be used as a script interpreter, also known as shebang. Here is an example self-contained Python script making use of this feature:

#!/usr/bin/env -S guix shell python python-numpy -- python3
import numpy
print("This is numpy", numpy.version.version)

You may pass any guix shell option, but there’s one caveat: the Linux kernel has a limit of 127 bytes on shebang length.

Development environments can be created as in the example below, which spawns an interactive shell containing all the dependencies and environment variables needed to work on Inkscape:

guix shell --development inkscape

Exiting the shell places the user back in the original environment before guix shell was invoked. The next garbage collection (see Invocación de guix gc) may clean up packages that were installed in the environment and that are no longer used outside of it.

As an added convenience, guix shell will try to do what you mean when it is invoked interactively without any other arguments as in:

guix shell

If it finds a manifest.scm in the current working directory or any of its parents, it uses this manifest as though it was given via --manifest. Likewise, if it finds a guix.scm in the same directories, it uses it to build a development profile as though both --development and --file were present. In either case, the file will only be loaded if the directory it resides in is listed in ~/.config/guix/shell-authorized-directories. This provides an easy way to define, share, and enter development environments.

By default, the shell session or command runs in an augmented environment, where the new packages are added to search path environment variables such as PATH. You can, instead, choose to create an isolated environment containing nothing but the packages you asked for. Passing the --pure option clears environment variable definitions found in the parent environment¹⁶; passing --container goes one step further by spawning a container isolated from the rest of the system:

guix shell --container emacs gcc-toolchain

The command above spawns an interactive shell in a container where nothing but emacs, gcc-toolchain, and their dependencies is available. The container lacks network access and shares no files other than the current working directory with the surrounding environment. This is useful to prevent access to system-wide resources such as /usr/bin on foreign distros.

This --container option can also prove useful if you wish to run a security-sensitive application, such as a web browser, in an isolated environment. For example, the command below launches Ungoogled-Chromium in an isolated environment, which:

• shares network access with the host
• inherits host’s environment variables DISPLAY and XAUTHORITY
• has access to host’s authentication records from the XAUTHORITY file
• has no information about host’s current directory

guix shell --container --network --no-cwd ungoogled-chromium \
  --preserve='^XAUTHORITY$' --expose="${XAUTHORITY}" \
  --preserve='^DISPLAY$' -- chromium

guix shell defines the GUIX_ENVIRONMENT variable in the shell it spawns; its value is the file name of the profile of this environment. This allows users to, say, define a specific prompt for development environments in their .bashrc (see Bash Startup Files in The GNU Bash Reference Manual):

if [ -n "$GUIX_ENVIRONMENT" ]
then
    export PS1="\u@\h \w [dev]\$ "
fi

... o para explorar el perfil:

$ ls "$GUIX_ENVIRONMENT/bin"

Las opciones disponibles se resumen a continuación.

--check

Set up the environment and check whether the shell would clobber environment variables. It’s a good idea to use this option the first time you run guix shell for an interactive session to make sure your setup is correct.

For example, if the shell modifies the PATH environment variable, report it since you would get a different environment than what you asked for.

Such problems usually indicate that the shell startup files are unexpectedly modifying those environment variables. For example, if you are using Bash, make sure that environment variables are set or modified in ~/.bash_profile and not in ~/.bashrc—the former is sourced only by log-in shells. See Bash Startup Files in The GNU Bash Reference Manual, for details on Bash start-up files.

--development

-D

Cause guix shell to include in the environment the dependencies of the following package rather than the package itself. This can be combined with other packages. For instance, the command below starts an interactive shell containing the build-time dependencies of GNU Guile, plus Autoconf, Automake, and Libtool:

guix shell -D guile autoconf automake libtool

--expression=expr

-e expr

Crea un entorno para el paquete o lista de paquetes a los que evalúa expr.

Por ejemplo, ejecutando:

guix shell -D -e '(@ (gnu packages maths) petsc-openmpi)'

inicia un shell con el entorno para esta variante específica del paquete PETSc.

Ejecutar:

guix shell -e '(@ (gnu) %base-packages)'

inicia un shell con todos los paquetes básicos del sistema disponibles.

Las órdenes previas usan únicamente la salida predeterminada de los paquetes dados. Para seleccionar otras salidas, tuplas de dos elementos pueden ser especificadas:

guix shell -e '(list (@ (gnu packages bash) bash) "include")'

See package->development-manifest, for information on how to write a manifest for the development environment of a package.

--file=archivo

-f archivo

Create an environment containing the package or list of packages that the code within file evaluates to.

Como un ejemplo, archivo puede contener una definición como esta (see Definición de paquetes):

(use-modules (guix)
             (gnu packages gdb)
             (gnu packages autotools)
             (gnu packages texinfo))

;; Augment the package definition of GDB with the build tools
;; needed when developing GDB (and which are not needed when
;; simply installing it.)
(package
  (inherit gdb)
  (native-inputs (modify-inputs (package-native-inputs gdb)
                   (prepend autoconf-2.69 automake texinfo))))

With the file above, you can enter a development environment for GDB by running:

guix shell -D -f gdb-devel.scm

--manifest=archivo

-m archivo

Crea un entorno para los paquetes contenidos en el objeto manifest devuelto por el código Scheme en file. Esta opción se puede repetir varias veces, en cuyo caso los manifiestos se concatenan.

Esto es similar a la opción del mismo nombre en guix package (see --manifest) y usa los mismos archivos de manifiesto.

See Writing Manifests, for information on how to write a manifest. See --export-manifest below on how to obtain a first manifest.

--export-manifest

Write to standard output a manifest suitable for --manifest corresponding to given command-line options.

This is a way to “convert” command-line arguments into a manifest. For example, imagine you are tired of typing long lines and would like to get a manifest equivalent to this command line:

guix shell -D guile git emacs emacs-geiser emacs-geiser-guile

Just add --export-manifest to the command line above:

guix shell --export-manifest \
  -D guile git emacs emacs-geiser emacs-geiser-guile

... and you get a manifest along these lines:

(concatenate-manifests
  (list (specifications->manifest
          (list "git"
                "emacs"
                "emacs-geiser"
                "emacs-geiser-guile"))
        (package->development-manifest
          (specification->package "guile"))))

You can store it into a file, say manifest.scm, and from there pass it to guix shell or indeed pretty much any guix command:

guix shell -m manifest.scm

Voilà, you’ve converted a long command line into a manifest! That conversion process honors package transformation options (see Opciones de transformación de paquetes) so it should be lossless.

--profile=perfil

-p perfil

Create an environment containing the packages installed in profile. Use guix package (see Invocación de guix package) to create and manage profiles.

--pure

Olvida las variables de entorno existentes cuando se construye un nuevo entorno, excepto aquellas especificadas con --preserve (véase más adelante). Esto tiene el efecto de crear un entorno en el que las rutas de búsqueda únicamente contienen las entradas del paquete.

--preserve=regexp

-E regexp

Cuando se usa junto a --pure, preserva las variables de entorno que corresponden con regexp—en otras palabras, las pone en una lista de variables de entorno que deben preservarse. Esta opción puede repetirse varias veces.

guix shell --pure --preserve=^SLURM openmpi … \
  -- mpirun …

Este ejemplo ejecuta mpirun en un contexto donde las únicas variables de entorno definidas son PATH, variables de entorno cuyo nombre empiece con ‘SLURM’, así como las variables “preciosas” habituales (HOME, USER, etc.).

--search-paths

Muestra las definiciones de variables de entorno que componen el entorno.

--system=sistema

-s sistema

Intenta construir para sistema—por ejemplo, i686-linux.

--container ¶

-C

Ejecuta la orden en un contenedor aislado. El directorio actual fuera del contenedor es asociado al interior del contenedor. Adicionalmente, a menos que se fuerce con --user, un directorio de prueba de la usuaria se crea de forma que coincida con el directorio actual de la usuaria, y /etc/passwd se configura adecuadamente.

El proceso lanzado se ejecuta como el usuario actual fuera del contenedor. Dentro del contenedor, tiene el mismo UID y GID que el usuario actual, a menos que se proporcione --user (véase más adelante).

--network

-N

Para contenedores, comparte el espacio de nombres de red con el sistema anfitrión. Los contenedores creados sin esta opción únicamente tienen acceso a la red local.

--link-profile

-P

For containers, link the environment profile to ~/.guix-profile within the container and set GUIX_ENVIRONMENT to that. This is equivalent to making ~/.guix-profile a symlink to the actual profile within the container. Linking will fail and abort the environment if the directory already exists, which will certainly be the case if guix shell was invoked in the user’s home directory.

Determinados paquetes se configuran para buscar en ~/.guix-profile archivos de configuración y datos;¹⁷ --link-profile permite a estos programas operar de la manera esperada dentro del entorno.

--user=usuaria

-u usuaria

Para contenedores, usa el nombre de usuaria usuaria en vez de la actual. La entrada generada en /etc/passwd dentro del contenedor contendrá el nombre usuaria; su directorio será /home/usuaria y ningún dato GECOS de la usuaria se copiará. Más aún, el UID y GID dentro del contenedor son 1000. usuaria no debe existir en el sistema.

Adicionalmente, cualquier ruta compartida o expuesta (véanse --share y --expose respectivamente) cuyo destino esté dentro de la carpeta actual de la usuaria será reasociada en relación a /home/usuaria; esto incluye la relación automática del directorio de trabajo actual.

# will expose paths as /home/foo/wd, /home/foo/test, and /home/foo/target
cd $HOME/wd
guix shell --container --user=foo \
     --expose=$HOME/test \
     --expose=/tmp/target=$HOME/target

Mientras esto limita el escape de la identidad de la usuaria a través de las rutas de sus directorios y cada uno de los campos de usuaria, esto es únicamente un componente útil de una solución de privacidad/anonimato más amplia—no una solución completa.

--no-cwd

El comportamiento predeterminado con contenedores es compartir el directorio de trabajo actual con el contenedor aislado e inmediatamente cambiar a dicho directorio dentro del contenedor. Si no se desea este comportamiento, --no-cwd indica que el directorio actual no se compartirá automáticamente y, en vez de cambiar a dicho directorio, se cambiará al directorio de la usuaria dentro del contenedor. Véase también --user.

--expose=fuente[=destino]

--share=fuente[=destino]

En contenedores, la --expose expone el sistema de archivos fuente del sistema anfitrión como un sistema de archivos de solo-lectura destino dentro del contenedor. --share de la misma manera expone el sistema de archivos con posibilidad de escritura. Si no se especifica destino, fuente se usa como el punto de montaje en el contenedor.

El ejemplo a continuación lanza una sesión interactiva de Guile en un contenedor donde el directorio principal de la usuaria es accesible en modo solo-lectura a través del directorio /intercambio:

guix shell --container --expose=$HOME=/exchange guile -- guile

--symlink=spec

-S spec

For containers, create the symbolic links specified by spec, as documented in pack-symlink-option.

--emulate-fhs

-F

When used with --container, emulate a Filesystem Hierarchy Standard (FHS) configuration within the container, providing /bin, /lib, and other directories and files specified by the FHS.

As Guix deviates from the FHS specification, this option sets up the container to more closely mimic that of other GNU/Linux distributions. This is useful for reproducing other development environments, testing, and using programs which expect the FHS specification to be followed. With this option, the container will include a version of glibc that will read /etc/ld.so.cache within the container for the shared library cache (contrary to glibc in regular Guix usage) and set up the expected FHS directories: /bin, /etc, /lib, and /usr from the container’s profile.

--nesting

-W

When used with --container, provide Guix inside the container and arrange so that it can interact with the build daemon that runs outside the container. This is useful if you want, within your isolated container, to create other containers, as in this sample session:

$ guix shell -CW coreutils
[env]$ guix shell -C guile -- guile -c '(display "hello!\n")'
hello!
[env]$ exit

The session above starts a container with coreutils programs available in PATH. From there, we spawn guix shell to create a nested container that provides nothing but Guile.

Another example is evaluating a guix.scm file that is untrusted, as shown here:

guix shell -CW -- guix build -f guix.scm

The guix build command as executed above can only access the current directory.

Under the hood, the -W option does several things:

• map the daemon’s socket (by default /var/guix/daemon-socket/socket) inside the container;
• map the whole store (by default /gnu/store) inside the container such that store items made available by nested guix invocations are visible;
• add the currently-used guix command to the profile in the container, such that guix describe returns the same state inside and outside the container;
• share the cache (by default ~/.cache/guix) with the host, to speed up operations such as guix time-machine and guix shell.

--rebuild-cache ¶

In most cases, guix shell caches the environment so that subsequent uses are instantaneous. Least-recently used cache entries are periodically removed. The cache is also invalidated, when using --file or --manifest, anytime the corresponding file is modified.

The --rebuild-cache forces the cached environment to be refreshed. This is useful when using --file or --manifest and the guix.scm or manifest.scm file has external dependencies, or if its behavior depends, say, on environment variables.

--root=archivo ¶

-r archivo

Hace que archivo sea un enlace simbólico al perfil para este entorno, y lo registra como una raíz del recolector de basura.

Esto es útil si desea proteger su entorno de la recolección de basura, hacerlo “persistente”.

When this option is omitted, guix shell caches profiles so that subsequent uses of the same environment are instantaneous—this is comparable to using --root except that guix shell takes care of periodically removing the least-recently used garbage collector roots.

In some cases, guix shell does not cache profiles—e.g., if transformation options such as --with-latest are used. In those cases, the environment is protected from garbage collection only for the duration of the guix shell session. This means that next time you recreate the same environment, you could have to rebuild or re-download packages.

See Invocación de guix gc, for more on GC roots.

guix shell also supports all of the common build options that guix build supports (see Opciones comunes de construcción) as well as package transformation options (see Opciones de transformación de paquetes).