The purpose of
guix environment is to assist in creating
Deprecation warning: The
guix environmentcommand is deprecated in favor of
guix shell, which performs similar functions but is more convenient to use. See Invoking
guix environmentis slated for eventual removal, but the Guix project is committed to keeping it until May 1st, 2023. Please get in touch with us at firstname.lastname@example.org if you would like to discuss it.
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,
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
Exiting from a Guix environment is the same as exiting from the shell, and
will place the user back in the old environment before
environment was invoked. The next garbage collection (see Invocando
guix gc) will clean up packages that were installed from within the environment
and are no longer used outside of it.
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 3 and NumPy:
guix environment --ad-hoc python-numpy python -- python3
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 --pure 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 Guix System, 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
Nota: The --container option requires Linux-libre 3.19 or newer.
Another typical use case for containers is to run security-sensitive
applications such as a web browser. To run Eolie, we must expose and share
some files and directories; we include
nss-certs and expose
/etc/ssl/certs/ for HTTPS authentication; finally we preserve the
DISPLAY environment variable since containerized graphical
applications won’t display without it.
guix environment --preserve='^DISPLAY$' --container --network \ --expose=/etc/machine-id \ --expose=/etc/ssl/certs/ \ --share=$HOME/.local/share/eolie/=$HOME/.local/share/eolie/ \ --ad-hoc eolie nss-certs dbus -- eolie
The available options are summarized below.
Set up the environment and check whether the shell would clobber environment variables. See --check, for more info.
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 Invocando
guix gc, for more on GC
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.
guix environment --ad-hoc -e '(@ (gnu) %base-packages)'
starts a shell with all the base system 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")'
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 Definindo pacotes):
(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.64 automake texinfo))))
Create an environment for the packages contained in the manifest object returned by the Scheme code in file. This option can be repeated several times, in which case the manifests are concatenated.
This is similar to the same-named option in
(see --manifest) and uses the same manifest
guix shell --export-manifest, for
information on how to “convert” command-line options into a manifest.
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
guile in an environment where Guile and Guile-SDL are
Note that this example implicitly asks for the default output of
guile-sdl, but it is possible to ask for a specific
glib:bin asks for the
bin output of
(see Pacotes com múltiplas saídas).
This option may be composed with the default behavior of
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.
Create an environment containing the packages installed in profile.
guix package (see Invocando
guix package) to create and
Unset existing environment variables when building the new environment, except those specified with --preserve (see below). This has the effect of creating an environment in which search paths only contain package inputs.
When used alongside --pure, preserve the environment variables matching regexp—in other words, put them on a “white list” of environment variables that must be preserved. This option can be repeated several times.
guix environment --pure --preserve=^SLURM --ad-hoc openmpi … \ -- mpirun …
This example runs
mpirun in a context where the only environment
variables defined are
PATH, environment variables whose name starts
with ‘SLURM’, as well as the usual “precious” variables (
Display the environment variable definitions that make up the environment.
Attempt to build for system—e.g.,
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. Inside the container, it has the same UID and GID as the current user, unless --user is passed (see below).
For containers, share the network namespace with the host system. Containers created without this flag only have access to the loopback device.
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
environment was invoked in the user’s home directory.
Certain packages are configured to look in ~/.guix-profile for configuration files and data;17 --link-profile allows these programs to behave as expected within the environment.
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. Furthermore, the UID and GID inside the container are 1000. 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.
For containers, the default behavior is to share the current working directory with the isolated container and immediately change to that directory within the container. If this is undesirable, --no-cwd will cause the current working directory to not be automatically shared and will change to the user’s home directory within the container instead. See also --user.
For containers, --expose (resp. --share) exposes the file system source from the host system as the read-only (resp. 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 read-only via the /exchange directory:
guix environment --container --expose=$HOME=/exchange --ad-hoc guile -- guile
For containers, emulate a Filesystem Hierarchy Standard (FHS) configuration
within the container, see
specification. 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 which 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:
/usr from the container’s profile.
guix environment also supports all of the common build options
guix build supports (see Opções de compilação comum) as well as
package transformation options (see Opções de transformação de pacote).
Users sometimes wrongfully augment
environment variables such as
PATH in their ~/.bashrc file. As
a consequence, when
guix environment launches it, Bash may read
~/.bashrc, thereby introducing “impurities” in these environment
variables. It is an error to define such environment variables in
.bashrc; instead, they should be defined in .bash_profile,
which is sourced only by log-in shells. See Bash Startup Files in The GNU Bash Reference Manual, for details on Bash start-up files.
For example, the
package inspects ~/.guix-profile/share/fonts for additional fonts.