Accessing Tools in Neurodesk

Author: Michèle Masson-Trottier

Date: 2026-03-10

License:

Note: If this notebook uses neuroimaging tools from Neurocontainers, those tools retain their original licenses. Please see Neurodesk citation guidelines for details.

Citation and Resources¶

Tools included in this workflow¶

• Neurodesk — Renton, A.I., Dao, T.T., Johnstone, T. et al. Neurodesk: an accessible, flexible and portable data analysis environment for reproducible neuroimaging. Nat Methods 21, 804–808 (2024). Hayashi et al. (2024)

• Lmod — McLay, R., Schulz, K.W., Barth, W.L., Minyard, T. Best Practices for the Deployment and Management of Production HPC Clusters. SC11, (2011). https://lmod.readthedocs.io

• FSL — Jenkinson, M., Beckmann, C.F., Behrens, T.E.J., Woolrich, M.W., Smith, S.M. FSL. NeuroImage 62, 782-790 (2012). Jenkinson et al. (2012)

• FreeSurfer — Fischl, B. FreeSurfer. NeuroImage 62, 774-781 (2012). Fischl (2012)

• ANTs — Avants, B.B., Tustison, N.J., Song, G., et al. A reproducible evaluation of ANTs similarity metric performance in brain image registration. NeuroImage 54, 2033-2044 (2011). Avants et al. (2011)

Dataset¶

• OpenNeuro ds000102 — Kelly, A.M.C. et al. (2008). Competition between functional brain networks mediates behavioral variability. NeuroImage 39, 527-537. Kelly et al. (2008). Dataset available at OpenNeuro.

Educational resources¶

• Neurodesk Documentation

• NeurodeskEDU

• Lmod User Guide

Statement of Need¶

Neurodesk provides access to a large collection of neuroimaging tools through containerised applications. New users often ask: how do I actually run my tools? The answer depends on which interface you’re using.

This tutorial is for anyone getting started with Neurodesk — from first-time users to experienced researchers exploring a different interface. It covers the four main ways to access tools (Jupyter Terminal, Jupyter Notebook, Neurodesktop Terminal, and the Neurodesktop Application Menu), and demonstrates that all methods share the same underlying module system by loading a different tool in each section — FSL, FreeSurfer, and ANTs — then confirming they are all available together at the end.

Learning Objectives¶

After completing this tutorial, you will be able to:

• Use ml commands to discover, load, and manage neuroimaging tools in a terminal

• Load tools programmatically inside a Jupyter notebook using await module.load()

• Launch tools from the Neurodesktop terminal and application menu

• Choose the appropriate access method for different tasks

• Combine tools loaded through different methods in a single session

Table of Contents¶

1. Jupyter Terminal — Loading FSL
2. Jupyter Notebook — Loading FreeSurfer
3. Neurodesktop Terminal — Loading ANTs
4. Neurodesktop Application Menu
5. Putting It All Together
6. Comparison and Quick Reference

Load software tools and install dependencies¶

1. Jupyter Terminal — Loading FSL¶

The Jupyter Terminal gives you a full shell session inside the Neurodesk environment. This is the most direct way to interact with tools, and it works identically to using a terminal on an HPC system with environment modules.

The JupyterLab interface in Neurodesk — this is where you’ll find the Terminal, Notebook, sidebar module panel, and file browser.

In this section, we’ll use it to load FSL.

Launching a terminal¶

From JupyterLab, you can open a terminal in two ways:

• Launcher tab — click Terminal under “Other”

• Menu — File > New > Terminal

The JupyterLab Launcher showing the Terminal option under “Neurodesk”.

Loading tools from the sidebar¶

The JupyterLab sidebar includes a Neurodesk module panel (provided by the jupyter-lmod extension) that lists all available software containers. You can browse or search by name, and click the “Load” button next to any tool to activate it — no terminal commands needed. Here in the example below, Connectome Workbench 2.1.0 is loaded from the sidebar, making its executables available in a new terminal.

The Neurodesk module panel in the JupyterLab sidebar. Click “Load” next to a tool to activate it.

Loading a tool from the sidebar sets the environment variables in the JupyterLab server process. This means:

• Notebook cells — tools loaded from the sidebar are immediately available via ! shell escapes and subprocess calls in a Notebook

• New terminals — any terminal opened after loading from the sidebar will inherit the loaded modules

• Already-open terminals — terminals that were opened before you clicked “Load” in the sidebar will not see the new module

Loading FSL with ml¶

Once you have a terminal open, you use the ml (module load) command to activate tools:

# List all available modules
ml avail

Example output of ml avail showing the list of available tools and versions.

# Load FSL
ml fsl/6.0.7.8

# Verify it's loaded
ml list

# Check that FSL tools are accessible
which bet

Example output of ml list showing the tools and versions that have been loaded in the terminal.

How ml works under the hood¶

ml is a shorthand for the module load command from Lmod. When you run ml fsl/6.0.7.8, Neurodesk:

1. Fetches the corresponding container (if not already cached)

2. Sets up environment variables (PATH, LD_LIBRARY_PATH, etc.)

3. Makes all executables from that tool available in your shell

This is transparent — once loaded, you just use the tool commands directly.

Managing modules¶

# Unload a specific module
ml -fsl

# Purge all loaded modules
ml purge

# Load a different version
ml fsl/6.0.7.4

import module

# Purge all loaded modules
await module.purge()

# Load a different version
await module.load('fsl/6.0.7.4')

# List what's loaded
await module.list()

Troubleshooting: Jupyter Terminal¶

2. Jupyter Notebook — Loading FreeSurfer¶

When working inside a Jupyter notebook (like this one), you can load Neurodesk tools programmatically using Python. This is ideal for reproducible analysis pipelines where you want your tool setup documented alongside your code.

Neurodesk launcher window to open a new Jupyter Notebook.

In this section, we’ll load FreeSurfer to demonstrate the notebook interface.

The module interface¶

Neurodesk provides a Python module package that mirrors the terminal’s ml commands using async/await syntax:

Running shell commands from a notebook¶

Once FreeSurfer is loaded, you can call its executables using the ! shell escape or subprocess:

Using Python wrappers¶

Some tools also have native Python interfaces. After loading the module, you can import them directly. For example, nibabel can read NIfTI and FreeSurfer .mgz files, letting you inspect and manipulate neuroimaging data directly in Python.

Let’s download a T1-weighted brain scan from OpenNeuro dataset ds000102 using DataLad, then load it with nibabel:

Troubleshooting: Jupyter Notebook¶

3. Neurodesktop Terminal — Loading ANTs¶

The Neurodesktop provides a full graphical Linux desktop environment that you can access directly from JupyterLab. To open it, click the Neurodesktop button in the JupyterLab Launcher (under “Notebook”).

Click “Neurodesktop” in the JupyterLab Launcher to open the desktop environment in a new tab.

Once open, a window will open. You’ll see a Linux desktop with a taskbar, file manager, and application menu.

The Neurodesktop environment — a full Linux desktop with taskbar, file manager, and application menu.

In this section, we’ll load ANTs from the Neurodesktop’s LXTerminal to demonstrate that the same module system works across all interfaces.

Opening a terminal in Neurodesktop¶

From the Neurodesktop, open LXTerminal from the taskbar at the bottom of the screen.

The Neurodesktop environment with LXTerminal open from the taskbar.

Loading ANTs with ml¶

The ml command works identically in the Neurodesktop terminal:

# Load ANTs
ml ants/2.5.3

# Verify it's loaded
ml list

# Check that ANTs tools are accessible
which antsRegistration
antsRegistration --version

This is the same module system as the Jupyter Terminal — the only difference is that here you also have access to a full graphical display, so you can launch GUI tools alongside your command-line work.

Launching GUI tools from the terminal¶

One advantage of the Neurodesktop terminal is that you can launch graphical tools directly:

# Load FSL and launch FSLeyes
ml fsl/6.0.7.8
fsleyes &

FSLeyes launched from the Neurodesktop terminal, displaying a brain image.

4. Neurodesktop Application Menu¶

The Neurodesktop includes an application menu that lets you launch tools with a single click — no terminal commands required. This is the easiest method for users who prefer a point-and-click workflow.

Using the application menu¶

The Applications menu showing Neurodesk tool categories on the desktop.

Step-by-step:

1. Click the Applications menu in the desktop taskbar

2. Navigate to Neurodesk

3. Browse categories (e.g., All Applications, Structural Imaging, Functional Imaging)

4. Click on the desired tool (e.g., FSLeyes 6.0.7.14)

5. Wait briefly while the container initialises (first launch may take a moment)

6. The application opens — ready to use!

The application menu automatically handles the ml load step behind the scenes. GUI tools open in their own window; CLI tools open in a pre-configured terminal.

Troubleshooting: Application Menu¶

5. Putting It All Together¶

Throughout this tutorial, we loaded different tools through different methods:

• FSL via the Jupyter Terminal (ml fsl/6.0.7.8)

• FreeSurfer via the Jupyter Notebook (await module.load('freesurfer/7.4.1'))

• ANTs via the Neurodesktop Terminal (ml ants/2.5.3)

• FSLeyes via the Neurodesktop Application Menu (point-and-click)

All methods use the same underlying module system. In a notebook, we can load all three together and verify they are available side by side:

Regardless of whether you load tools from a Jupyter terminal, a notebook cell, or the Neurodesktop — they all share the same environment. You can mix and match access methods within a single session.

6. Comparison and Quick Reference¶

Dependencies in Jupyter/Python¶

Using the package watermark to document system environment and software versions used in this notebook.