5.10 Invoking guix environment

The purpose of guix environment is to assist hackers in creating reproducible development environments without polluting their package profile. The guix environment tool takes one or more packages, builds all of their inputs, and creates a shell environment to use them.

The general syntax is:

guix environment options package…

The following example spawns a new shell set up for the development of GNU Guile:

guix environment guile

If the needed dependencies are not built yet, guix environment automatically builds them. The environment of the new shell is an augmented version of the environment that guix environment was run in. It contains the necessary search paths for building the given package added to the existing environment variables. To create a “pure” environment, in which the original environment variables have been unset, use the --pure option¹⁵.

guix environment 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

... or to browse the profile:

$ ls "$GUIX_ENVIRONMENT/bin"

Additionally, more than one package may be specified, in which case the union of the inputs for the given packages are used. For example, the command below spawns a shell where all of the dependencies of both Guile and Emacs are available:

guix environment guile emacs

Sometimes an interactive shell session is not desired. An arbitrary command may be invoked by placing the -- token to separate the command from the rest of the arguments:

guix environment guile -- make -j4

In other situations, it is more convenient to specify the list of packages needed in the environment. For example, the following command runs python from an environment containing Python 2.7 and NumPy:

guix environment --ad-hoc python2-numpy python-2.7 -- python

Furthermore, one might want the dependencies of a package and also some additional packages that are not build-time or runtime dependencies, but are useful when developing nonetheless. Because of this, the --ad-hoc flag is positional. Packages appearing before --ad-hoc are interpreted as packages whose dependencies will be added to the environment. Packages appearing after are interpreted as packages that will be added to the environment directly. For example, the following command creates a Guix development environment that additionally includes Git and strace:

guix environment guix --ad-hoc git strace

Sometimes it is desirable to isolate the environment as much as possible, for maximal purity and reproducibility. In particular, when using Guix on a host distro that is not GuixSD, it is desirable to prevent access to /usr/bin and other system-wide resources from the development environment. For example, the following command spawns a Guile REPL in a “container” where only the store and the current working directory are mounted:

guix environment --ad-hoc --container guile -- guile

Note: The --container option requires Linux-libre 3.19 or newer.

The available options are summarized below.

--root=file

-r file

Make file a symlink to the profile for this environment, and register it as a garbage collector root.

This is useful if you want to protect your environment from garbage collection, to make it “persistent”.

When this option is omitted, the environment is protected from garbage collection only for the duration of the guix environment session. This means that next time you recreate the same environment, you could have to rebuild or re-download packages. See Invoking guix gc, for more on GC roots.

--expression=expr

-e expr

Create an environment for the package or list of packages that expr evaluates to.

For example, running:

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

starts a shell with the environment for this specific variant of the PETSc package.

Running:

guix environment --ad-hoc -e '(@ (gnu) %base-packages)'

starts a shell with all the GuixSD base packages available.

The above commands only use the default output of the given packages. To select other outputs, two element tuples can be specified:

guix environment --ad-hoc -e '(list (@ (gnu packages bash) bash) "include")'

--load=file

-l file

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

As an example, file might contain a definition like this (see Defining Packages):

(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 `(("autoconf" ,autoconf-2.64)
                   ("automake" ,automake)
                   ("texinfo" ,texinfo)
                   ,@(package-native-inputs gdb))))

--manifest=file

-m file

Create an environment for the packages contained in the manifest object returned by the Scheme code in file.

This is similar to the same-named option in guix package (see --manifest) and uses the same manifest files.

--ad-hoc

Include all specified packages in the resulting environment, as if an ad hoc package were defined with them as inputs. This option is useful for quickly creating an environment without having to write a package expression to contain the desired inputs.

For instance, the command:

guix environment --ad-hoc guile guile-sdl -- guile

runs guile in an environment where Guile and Guile-SDL are available.

Note that this example implicitly asks for the default output of guile and guile-sdl, but it is possible to ask for a specific output—e.g., glib:bin asks for the bin output of glib (see Packages with Multiple Outputs).

This option may be composed with the default behavior of guix environment. Packages appearing before --ad-hoc are interpreted as packages whose dependencies will be added to the environment, the default behavior. Packages appearing after are interpreted as packages that will be added to the environment directly.

--pure

Unset existing environment variables when building the new environment. This has the effect of creating an environment in which search paths only contain package inputs.

--search-paths

Display the environment variable definitions that make up the environment.

--system=system

-s system

Attempt to build for system—e.g., i686-linux.

--container

-C

Run command within an isolated container. The current working directory outside the container is mapped inside the container. Additionally, unless overridden with --user, a dummy home directory is created that matches the current user’s home directory, and /etc/passwd is configured accordingly. The spawned process runs as the current user outside the container, but has root privileges in the context of the container.

--network

-N

For containers, share the network namespace with the host system. Containers created without this flag only have access to the loopback device.

--link-profile

-P

For containers, link the environment profile to ~/.guix-profile within the container. This is equivalent to running the command ln -s $GUIX_ENVIRONMENT ~/.guix-profile within the container. Linking will fail and abort the environment if the directory already exists, which will certainly be the case if guix environment was invoked in the user’s home directory.

Certain packages are configured to look in ~/.guix-profile for configuration files and data;¹⁶ --link-profile allows these programs to behave as expected within the environment.

--user=user

-u user

For containers, use the username user in place of the current user. The generated /etc/passwd entry within the container will contain the name user; the home directory will be /home/USER; and no user GECOS data will be copied. user need not exist on the system.

Additionally, any shared or exposed path (see --share and --expose respectively) whose target is within the current user’s home directory will be remapped relative to /home/USER; this includes the automatic mapping of the current working directory.

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

While this will limit the leaking of user identity through home paths and each of the user fields, this is only one useful component of a broader privacy/anonymity solution—not one in and of itself.

--expose=source[=target]

For containers, expose the file system source from the host system as the read-only file system target within the container. If target is not specified, source is used as the target mount point in the container.

The example below spawns a Guile REPL in a container in which the user’s home directory is accessible read-only via the /exchange directory:

guix environment --container --expose=$HOME=/exchange --ad-hoc guile -- guile

--share=source[=target]

For containers, share the file system source from the host system as the writable file system target within the container. If target is not specified, source is used as the target mount point in the container.

The example below spawns a Guile REPL in a container in which the user’s home directory is accessible for both reading and writing via the /exchange directory:

guix environment --container --share=$HOME=/exchange --ad-hoc guile -- guile

guix environment also supports all of the common build options that guix build supports (see Common Build Options).