Hands-on reproducible computing with Guix

Welcome to Hands-on reproducible computing with Guix, a workshop designed to teach you the fundamentals of Guix for reproducible computation.

This workshop is organized as follows:

  • a 15-minute introductory talk
  • a 60-minute live-coding session
  • a 15-minute closing talk

The live-coding session requires some preparatory work and experimental setup, which are detailed below. Please make sure to run through the details as early as possible, since this setup requires bandwidth and time, both of which will be limited during the actual session.

Experimental setup

This section provides details to get a working setup for the live-coding session.

We will be working on a representative example from the neuroimaging community, which requires downloading appropriate tooling and data to process and visualize results.

Please be careful with some set of instructions which are operating system specific.

Experimental data

Please download them here. The password is “RSECon25”.

You will find two zip archives containing the structural imaging data (OASIS-1) and the anatomical template data (MNI152Lin).

Conda environment

The experiment can be run using the Conda manifest available here.

Ensure you have a working Conda-compatible installation. We recommend using micromamba if you do not have one yet.

$ cd /path/to/guix-workshop/src
$ micromamba create -f environment.yml
$ micromamba activate guix-workshop

The resulting guix-workshop environment features the fsleyes GUI application, which you are welcome to use for visualizing the experimental data and results.

Guix installation

On Windows

Guix on Windows requires the Windows Subsystem for Linux, aka WSL. Please follow these instructions to set WSL up with the default Linux distribution (Ubuntu).

Then, follow the instructions from the Linux section below.

On macOS

Guix on macOS requires the macOS Subsystem for Guix, aka MSG. Please follow the instuctions below to set MSG up.

  1. Install MSG through Homebrew:

    $ brew tap MSG/apps https://forge.superkamiguru.org/MSG/homebrew-apps
$ brew install msg-cli

  2. Verify shell access:

    $ msg machine init
$ msg machine start
$ msg shell

On Linux

Guix is supported natively on Linux.

  • Download the latest binary file :
    • Visit the official Guix website: https://guix.gnu.org/
    • Navigate to Download > Latest in the menu.
    • Download the GNU Guix binary (x86_64 version).
    • Open a terminal
    GUIX_BINARY_FILE=<path_to_the_guix_binary_archive>
wget -O guix-install.sh https://guix.gnu.org/install.sh
chmod +x guix-install.sh
./guix-install.sh

On Grid’5000 (HPC)

To participate in the workshop using Grid’5000, you do not need to create an account yourself. I will set up a temporary account for you, but you must provide the following details by September 8, 2025:

  • Last name
  • First name
  • Institutional email address

Please send this information to Julien Castelneau and Ghislain Vaillant.

Warning

Accounts will be created using the Grid’5000 Teaching Lab procedure.

You will receive connection instructions by email once your account is ready.

  • Summary of Connection Steps (from the email you will receive):

    Once your account is ready, you will receive an email with all the necessary details. Here’s a summary of what you’ll need to do:

    • Account creation with password and public ssh key

      Note

      Display you public ssh key with ssh-add -L

    • Update your ~/.ssh/config file

      Host g5k
  User <login>
  Hostname access.grid5000.fr
  ForwardAgent no

Host *.g5k
  User <login>
  ProxyCommand ssh g5k -W "$(basename %h .g5k):%p"
  ForwardAgent no
      Note

      Replace the <login> placeholder with the one you received in the confirmation email from Grid’5000.

    • Use the following command to connect:

      ssh grenoble.g5k

Setup Guix channels

  • Create the file channels.scm and edit it using your preferred text editor (nano, vim, emacs, etc.):

    $ touch channels.scm
$ $(EDITOR) channels.scm

  • Copy and paste the following content into the file:

    (list (channel
        (name 'guix-science-nonfree)
        (url "https://codeberg.org/guix-science/guix-science-nonfree.git")
        (branch "master")
        (commit
          "93e46c38bf7a6158d23f578e893759b7e44eccbb"))
      (channel
        (name 'guix)
        (url "https://git.guix.gnu.org/guix.git")
        (branch "master")
        (commit
          "a5bf38cf2a50d3356a4a33ff5b50e3fdc7387d4a")
        (introduction
          (make-channel-introduction
            "9edb3f66fd807b096b48283debdcddccfea34bad"
            (openpgp-fingerprint
              "BBB0 2DDF 2CEA F6A8 0D1D  E643 A2A0 6DF2 A33A 54FA"))))
      (channel
        (name 'guix-science)
        (url "https://codeberg.org/guix-science/guix-science.git")
        (branch "master")
        (commit
          "67b23a6caa4fa32f2bf35a1730ca455a6b4d5fd7")
        (introduction
          (make-channel-introduction
            "b1fe5aaff3ab48e798a4cce02f0212bc91f423dc"
            (openpgp-fingerprint
              "CA4F 8CF4 37D7 478F DA05  5FD4 4213 7701 1A37 8446"))))
      (channel
        (name 'guix-past)
        (url "https://codeberg.org/guix-science/guix-past.git")
        (branch "master")
        (commit
          "b14d7f997ae8eec788a7c16a7252460cba3aaef8")
        (introduction
          (make-channel-introduction
            "0c119db2ea86a389769f4d2b9c6f5c41c027e336"
            (openpgp-fingerprint
              "3CE4 6455 8A84 FDC6 9DB4  0CFB 090B 1199 3D9A EBB5")))))

  • Update Guix

    $ guix pull -C channels.scm

Open a Guix shell

  • Create the file manifest.scm and edit it using your preferred text editor (e.g., nano, vim, or gedit):

    $ touch manifest.scm
$ $(EDITOR) manifest.scm

  • Copy and paste the following content into the file:

    (use-modules (gnu packages base))
(use-modules (gnu packages gawk))
(use-modules (gnu packages python))
(use-modules (gnu packages vim))
(use-modules (guix-science packages neuroscience))
(use-modules (guix-science-nonfree packages fsl))

(packages->manifest (list
                    (generate-fsl-distribution (list fsl-base fsl-misc-c fsl-bet2 fsl-avwutils fsl-fast4 fsl-flirt python-fslpy))
                    coreutils
                    fsleyes
                    gawk
                    grep
                    python-nipype
                    python-wrapper
                    sed
                    vim
                    which))

  • Run the time-machine

    $ guix time-machine -C channels.scm -- shell -C -m manifest.scm