GNU Guix: Reproducible Software Environments for Research

GNU Guix is a transactional package manager, and a Linux distribution built on it, that lets a researcher describe the exact software an analysis needs and rebuild that environment later or on another machine. Its manual describes guix shell as creating one-off software environments without changing your profile, and guix time-machine as a way to reproduce a computation in an identical environment by running a past revision of Guix. Guix is free software, licensed under the AGPL and powered by GNU Guile.

This guide covers what Guix is used for in research, how to install it from the official source, a worked workflow that pins an environment with a manifest and a channels file, how to read the output, and the problems the manual itself warns about. It sits in the computational reproducibility part of research practice: the goal is a computational environment that someone else can recreate from files you publish alongside the analysis.

What GNU Guix is used for in research

The Guix-HPC project, which promotes Guix for high-performance and research computing, describes it as a package manager that installs software per user, and says to think of it as virtualenv but not limited to Python. It states that a package built from a specific commit on a laptop is usually bit-for-bit identical to the same package built on an HPC cluster, and that the distribution plus its channels offer more than 50,000 packages. The practical consequences for a research group are these:

• Declared environments. The list of software an analysis needs lives in a file (a manifest) that can be committed next to the code.
• Pinned revisions. The state of Guix itself, meaning which package definitions were in force, can be recorded and replayed.
• Per-user installs. Packages are installed per user, so a researcher on a shared cluster does not need administrator rights to install software.
• Disposable environments. guix shell creates a throwaway environment for one task and leaves your profile untouched.

Guix is not the only way to capture an environment. A container image records a built environment, whereas a Guix manifest plus channels file records how to build it. The two can be combined; the free alternatives section below compares what each approach records.

Install or access GNU Guix (official source only)

The official download page lists Guix 1.5.0. Guix System, the full distribution, can be installed on i686, x86_64 and AArch64 machines. For an existing GNU/Linux system, the binary tarball is available for x86_64, i686, armhf, aarch64, powerpc64le and riscv64. The manual notes that some distributions package Guix themselves (it names openSUSE, Alpine and NixOS), but the packaged version may be older than the one on the download page.

Install on a system that does not have Guix

The manual’s binary installation section is for systems that do not already run Guix. The installer script needs Bash, GnuPG, GNU tar, wget and Xz, and on systemd systems also newgidmap and newuidmap from the uidmap package. As root, the manual gives these commands:

cd /tmp
wget https://guix.gnu.org/guix-install.sh
chmod +x guix-install.sh
./guix-install.sh

The script sets up substitutes, which are pre-built binaries fetched from build farms so you do not compile everything locally. Substitute servers must be authorized with guix archive --authorize; the manual names the build farms bordeaux.guix.gnu.org and ci.guix.gnu.org. Read the installer’s prompts, because the manual also documents a --uninstall flag that irreversibly deletes Guix files, so do not run it unless you intend to remove the installation.

Step-by-step: a reproducible analysis environment

The steps below follow the commands in the Guix manual (version 1.5.0). They build a pinned environment for an analysis in a Python project; substitute your own packages.

Step 1. Try an environment with guix shell

Run an interpreter inside a temporary environment without installing anything permanently:

guix shell python python-numpy -- python3

The manual stresses that you must include the main python package in the list, otherwise PYTHONPATH is not set up and the interpreter will not find the libraries. When the command exits, your own profile is unchanged. Inside the shell, the GUIX_ENVIRONMENT variable is set.

Step 2. Isolate the environment when it matters

By default, the shell inherits variables from the parent environment. Add --pure to clear them, so hidden variables from your login shell cannot influence a result. For stronger isolation, --container runs the environment in a container: the manual’s example is guix shell --container emacs gcc-toolchain. A container has no network access and shares only the current working directory with the host. Options exist to change that: --network allows network access, --no-cwd stops sharing the working directory, --expose shares additional host paths, and --preserve keeps selected environment variables.

Step 3. Write the environment down as a manifest

A manifest declares what a profile or environment contains. The manual’s route from an interactive setup is --export-manifest, which writes a manifest from an existing profile (the manual calls the result an approximation, intended to help migrate from imperative guix install use to declarative management). Save the result as manifest.scm in the project directory and run:

guix shell -m manifest.scm

With no arguments at all, guix shell looks in the current directory and its parents for manifest.scm (used as --manifest) or guix.scm (used as --development --file). It only loads such a file if the directory is listed in ~/.config/guix/shell-authorized-directories, a safeguard against running code from an untrusted checkout. For a package’s build dependencies, guix shell --development followed by the package name sets up a development environment.

Step 4. Record the exact Guix revision

A manifest names packages, but what those names resolve to depends on which revision of Guix and its channels you use. Record that revision:

guix describe -f channels > channels.scm

guix describe shows the channels and commits in use; the -f channels format prints them as a channel list you can save. The manual says that this list, fed to guix pull -C on another machine or at a later time, instantiates that exact Guix revision and therefore replicates the complete software environment. Commit both manifest.scm and channels.scm with your analysis code.

Step 5. Rebuild later with guix time-machine

guix time-machine runs a command with a different revision of Guix. The manual’s own example fetches the v1.2.0 tag and starts a container with Guile from that time:

guix time-machine --commit=v1.2.0 -- environment -C --ad-hoc guile -- guile

The manual notes that guix environment has since been subsumed by guix shell. The -C file (or --channels=file) option reads the channel list from a file, so a pinned analysis is run as:

guix time-machine -C channels.scm -- shell -m manifest.scm -- python3 analysis.py

The first run can be expensive because that Guix revision has to be fetched and built; the manual says the result is cached afterwards. Without -C or --commit, time-machine uses the channels in ~/.config/guix/channels.scm, /etc/guix/channels.scm or the default channels. The -q option ignores those configuration files.

Output and how to read it

Guix reports its work in a few places that matter for a research record. A guix shell session prints what it is going to build or download (often substitutes) before dropping you into a shell. Inside, echo $GUIX_ENVIRONMENT shows the environment is active. guix describe prints the channel name, repository URL and commit hash of the Guix in use; those commit hashes are the identifiers that make a rerun exact. The saved channels.scm is Scheme code evaluating to a list of channel objects, so it can be read by a person as well as by Guix.

For a methods section or a repository README, cite the contents of the two files rather than a Guix version number alone: the manifest lists the software, and the channels file pins the commits that define what each name means. The data table below summarises the commands used here and what each produces.

Troubleshooting

Python cannot find numpy or other libraries

The manual’s own example lists both python and python-numpy. Leaving out the main python package means PYTHONPATH is not set and the library cannot be found.

Plain guix shell does nothing or is refused

Automatic loading of manifest.scm or guix.scm only happens for directories listed in ~/.config/guix/shell-authorized-directories. Pass the file explicitly with -m manifest.scm if you do not want to authorize the directory.

The environment does not look like the one I defined

Variables from the parent environment can leak into a shell. Use --pure to clear them, or --container for full isolation. The manual also provides a --check option for guix shell, which is useful for detecting a setup file such as ~/.bashrc overriding the environment variables Guix sets, such as PATH.

Substitutes are not used and everything builds from source

Substitute servers must be authorized with guix archive --authorize. The installer normally configures this, but if you installed Guix another way, the manual’s installation chapter describes the build-farm keys to authorize.

time-machine rejects an old commit

The manual says guix time-machine refuses commits older than v0.16.0, released in December 2018. It also warns that old revisions receive no security fixes, so treat such environments with care.

Free alternatives and complements

Guix-HPC compares Guix with Python’s virtualenv, noting that Guix is not limited to Python. For other tools, consult their own documentation; the table below only states what each category records, which is the practical difference for reproducibility.

Approach	What it records	Where covered
Guix manifest plus channels file	The package list and the exact Guix commits that define it	Guix manual: guix shell, guix describe, guix time-machine
Python virtualenv	An isolated set of Python packages, Python only	Guix-HPC comparison ("VirtualEnv but not limited to Python")
Container image	A built environment, shared as an artifact	Container image term page

Frequently asked questions

What is GNU Guix?

GNU Guix is a transactional package manager and Linux distribution (Guix System) from the GNU Project, written with GNU Guile and released under the AGPL. Researchers use it to declare, share and rebuild software environments.

Does Guix replace guix environment?

Yes. The manual says guix shell supersedes guix environment, and that guix environment has been subsumed by it.

Can I use Guix on a cluster without administrator rights?

Guix-HPC says packages are installed per user and links a cluster-wide installation guide for administrators. Check with your cluster’s administrators about whether Guix is already provided.

Which architectures does Guix support?

Guix System installs on i686, x86_64 and AArch64; the binary tarball covers x86_64, i686, armhf, aarch64, powerpc64le and riscv64 (download page, Guix 1.5.0).

How far back can time-machine go?

The manual says it refuses commits older than v0.16.0 (December 2018), and that old revisions have no security fixes.

Sources

• GNU Guix Reference Manual: Invoking guix shell, read 2026-11-14
• Invoking guix describe, read 2026-11-14
• Invoking guix time-machine, read 2026-11-14
• Invoking guix package, read 2026-11-14
• Binary Installation, read 2026-11-14
• GNU Guix download page, read 2026-11-14
• Guix-HPC, read 2026-11-14