This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Local

For simple interface and local installation

1: Examples
2: Neurodesk App

1 - Examples

Installation Examples

On this page we show specific examples of the different ways of how Neurodesk can be installed on a local computer. We start from the highest level using the Neurodesk app, then go lower level via docker, neurocommand and down to the lowest level using neurocontainers. We also show on each level how containers can be streamed via CVMFS or downloaded locally.

Running Neurodesk on a Ubuntu 24.04 computer

On a linux machine you have mutliple options to use Neurodesk:

Highest abstraction level, and easiest option: Neurodeskapp - this provides you a full Linux desktop with everything configured you need. You do not need to think about Docker or Singularity containers and you can just get your work done. This is the recommended option.
High abstraction level: Running Neurodesktop via Docker manually - you still get the desktop with everything configured, but you now have to manage the docker container yourself. This is useful when the app doesn’t work well - for example in a remote SSH setup.
Middle abstraction level: Use the containers through wrapper scripts on the terminal through Neurocommand - this is great if you don’t need a full desktop environment and you want to use the neurodesk tools in your scripts. Neurocommand handles multiple containers for you and you just run your tools as you are used to without having to think about the fact that they are running in singularity/apptainer containers
Low abstraction level: Use the containers on the terminal directly - if you just want ot use the containers directly and you want to do everything yourself, that’s the best option for you :)

Highest abstraction level, and easiest option: Neurodeskapp

Download Neurodeskapp: https://github.com/NeuroDesk/neurodesk-app/releases/latest/download/NeurodeskApp-Setup-Debian-x64.deb

and Install:

sudo apt install ./NeurodeskApp-Setup-Debian-x64.deb

Install Docker:

# Add Docker's official GPG key:
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources:
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update

sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

sudo groupadd docker
sudo usermod -aG docker $USER
newgrp docker

sudo chown root:docker /var/run/docker.sock
sudo chmod 666 /var/run/docker.sock

After installation run the following command to verify that Docker is working correctly:

docker run hello-world

The Neurodeskapp can be launched directly from the application menu, or by running the neurodeskapp command in the command line.

In the Neurodeskapp settings you can choose if you want to stream or download containers to your system.

more information can be found here: https://neurodesk.org/docs/getting-started/local/neurodeskapp/

High abstraction level: Running Neurodesktop via Docker manually

If you run Ubuntu > 23.10 and you haven’t installed the Neurodeskapp before you need to create this apparmor profile under /etc/apparmor.d/neurodeskapp

echo -e "# This profile allows everything and only exists to give the\n# application a name instead of having the label \"unconfined\"\n\nabi <abi/4.0>,\ninclude <tunables/global>\n\nprofile neurodeskapp \"/opt/NeurodeskApp/neurodeskapp\" flags=(unconfined) {\n  userns,\n\n  # Site-specific additions and overrides. See local/README for details.\n  include if exists <local/neurodeskapp>\n}" | sudo tee /etc/apparmor.d/neurodeskapp

you also need to create the ~/neurodesktop-storage folder if you haven’t used the app before:

mkdir -p ~/neurodesktop-storage

Make sure you have Docker installed and configured correctly (see Neurodeskapp for instructions), then run in a terminal:

docker volume create neurodesk-home &&
sudo docker run \
  --shm-size=1gb -it --security-opt apparmor=neurodeskapp --privileged --user=root --name neurodesktop \
  -v ~/neurodesktop-storage:/neurodesktop-storage \
  --mount source=neurodesk-home,target=/home/jovyan \
  -e NB_UID="$(id -u)" -e NB_GID="$(id -g)" \
  -p 8888:8888 \
  -e NEURODESKTOP_VERSION=2025-06-10 vnmd/neurodesktop:2025-06-10

Then open the jupyter link with the token displayed in your browser. Make sure it starts with 127.0.0.1:8888/lab&token=…

You can also add a flag to the docker command to activate the offline mode: -e CVMFS_DISABLE=true

when finished, make sure to delete the container - otherwise, you will get an error the next time you run the docker command:

docker rm neurodesktop

If you want to pass your GPU into the desktop, first install this on the host:

# Manually set the distribution to ubuntu22.04 (works with Ubuntu 24.04) - because it doens't exist yet for 24.04
distribution="ubuntu22.04"

# Add the NVIDIA container toolkit repo using the 22.04 version
curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | \
  sed 's|^deb |deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit.gpg] |' | \
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list > /dev/null

# Update package lists
sudo apt update
sudo apt install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

Then start the neurodesktop container with the GPU flag:

sudo docker run \
  --shm-size=1gb -it --privileged --user=root --name neurodesktop \
  -v ~/neurodesktop-storage:/neurodesktop-storage \
  -e NB_UID="$(id -u)" -e NB_GID="$(id -g)" \
  --gpus all \
  -p 8888:8888 \
  -e NEURODESKTOP_VERSION=2025-06-10 vnmd/neurodesktop:2025-06-10

then export the –nv flag

export neurodesk_singularity_opts="--nv"

more information can be found here: https://neurodesk.org/docs/getting-started/neurodesktop/linux/

Middle abstraction level: Use the containers through wrapper scripts on the terminal through Neurocommand

For this you do not need Docker, but rather Apptainer or Singularity:

sudo apt-get install -y software-properties-common
sudo add-apt-repository -y ppa:apptainer/ppa
sudo apt-get update
sudo apt-get install -y apptainer
sudo apt-get install -y apptainer-suid

Make sure you have Python configured on your system with pip3:

sudo apt install python3-pip

Then install neurocommand:

cd ~
git clone https://github.com/NeuroDesk/neurocommand.git 
cd neurocommand 
python3 -m venv ./venv
./venv/bin/pip3 install -r neurodesk/requirements.txt
bash build.sh --cli
export APPTAINER_BINDPATH=`pwd -P`

now you can search and install containers:

# this searches for containers and you can install individual containers by running the install commands displayed 
bash containers.sh itksnap

# this installs all containers matching the pattern itksnap
bash containers.sh --itksnap

then link the containers directory to the neurodesktop-storage:

ln -s $PWD/local/containers/ ~/neurodesktop-storage/

then you can install lmod:

sudo apt install lmod

and configure lmod:

# Create the module.sh file
sudo bash -c 'cat > /usr/share/module.sh << "EOL"
# system-wide profile.modules                                          #
# Initialize modules for all sh-derivative shells                      #
#----------------------------------------------------------------------#
trap "" 1 2 3

case "$0" in
  -bash|bash|*/bash) . /usr/share/lmod/8.6.19/init/bash ;;
     -ksh|ksh|*/ksh) . /usr/share/lmod/8.6.19/init/ksh ;;
     -zsh|zsh|*/zsh) . /usr/share/lmod/8.6.19/init/zsh ;;
      -sh|sh|*/sh) . /usr/share/lmod/8.6.19/init/sh ;;
          *) . /usr/share/lmod/8.6.19/init/sh ;;  # default for scripts
esac

trap - 1 2 3
EOL'

then add the module setup to your ~/.bashrc:

cat >> ~/.bashrc << 'EOL'
if [ -f '/usr/share/module.sh' ]; then source /usr/share/module.sh; fi

if [ -d /cvmfs/neurodesk.ardc.edu.au/neurodesk-modules ]; then
  module use /cvmfs/neurodesk.ardc.edu.au/neurodesk-modules/*
else
  export MODULEPATH="~/neurodesktop-storage/containers/modules"              
  module use $MODULEPATH
fi
EOL

make sure you have set the APPTAINER_BINDPATH to all directories that you want the containers to access

export APPTAINER_BINDPATH=`/data,/scratch`

you can also add this to your ~/.bashrc

then restart the terminal you can load and run the software using:

ml itksnap
itksnap

If you need nvidia gpu support activate via exporting this environment variable:

export neurodesk_singularity_opts='--nv'

If you get errors like this:

/opt/itksnap-4.0.2/lib/snap-4.0.2/ITK-SNAP: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.38' not found (required by /.singularity.d/libs/libGLX.so.0)
/opt/itksnap-4.0.2/lib/snap-4.0.2/ITK-SNAP: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.38' not found (required by /.singularity.d/libs/libEGL.so.1)
/opt/itksnap-4.0.2/lib/snap-4.0.2/ITK-SNAP: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.38' not found (required by /.singularity.d/libs/libGLdispatch.so.0)

This means that the glibc versions inside the container and outside the container are not compatible. You can either disable the GPU flag –nv or use a newer version of the container.

If you do not want to download the containers you can also stream the containers using CVMFS: https://neurodesk.org/docs/getting-started/neurocontainers/cvmfs/

more information: https://neurodesk.org/docs/getting-started/neurocommand/linux-and-hpc/

Low abstraction level: Use the containers on the terminal directly

for this you only need apptainer or singularity installed. See above for installation instructions.

Then you can download a container and run it directly:

#find out which containers are available:
curl -s https://raw.githubusercontent.com/NeuroDesk/neurocommand/main/cvmfs/log.txt

#select a container and download it:
export container=itksnap_3.8.0_20201208
curl -X GET https://neurocontainers.neurodesk.org/$container.simg -O

singularity shell itksnap_3.8.0_20201208.simg
itksnap

if you need nvidia GPU support, add –nv:

singularity shell --nv itksnap_3.8.0_20201208.simg
itksnap

If you want to stream the containers, follow these instructions for setting up CVMFS: https://neurodesk.org/docs/getting-started/neurocontainers/cvmfs/

then you can run:

singularity shell /cvmfs/neurodesk.ardc.edu.au/containers/itksnap_3.8.0_20201208/itksnap_3.8.0_20201208.simg

and the container will be streamed to you :)

More information about Download (offline) mode: https://neurodesk.org/docs/getting-started/neurocontainers/singularity/

2 - Neurodesk App

A cross-platform desktop application for Neurodesk: The easiest way to use Neurodesktop

Determine System Privileges

Before running the app, check whether your system has privileged access (root/admin permissions). This determines which engine you need to use to run the app:

If you have privileged access → Use Docker or Podman Engine

If you do NOT have privileged access → Use TinyRange Engine, or run remote instance

Minimum System Requirements

At least 5GB free space for neurodesktop base image.
One of the following options, depending on system privileges:

With privileged access: Docker or Podman to run respective engines
Without privileged access: TinyRange Engine (included with Neurodesk App) and QEMU (only on macOS)

Downloading Neurodesk App

On Microsoft edge, follow these steps to download the executable file:

Installing Docker

Docker is required for starting a local instance of Neurodesk.
If only connecting to a remote Neurodesk servers, you may skip Installing Docker

The Neurodesk App requires Docker to be installed on your computer. If you already have Docker installed, you can skip this step.

After installation, open a terminal (Linux/macOS) or command prompt (Windows) and run the following command to verify that Docker is working correctly:

docker --version
docker run hello-world

Installing QEMU

QEMU is only needed if your using TinyRange on macOS. It is not needed on Windows or Linux using TinyRange since it’s included in the install.

The easist way to install QEMU on macOS is using Homebrew:

brew install qemu

You can verify the installation by running:

qemu-system-aarch64 --version

Installing Neurodesk App

If you have an existing Neurodesk App installation, please first uninstall it by following the uninstall instructions here. Then, install the app for your system:

Debian, Ubuntu Linux Installer: sudo apt install -f ./NeurodeskApp-Setup-Debian.deb
Red Hat, Fedora, SUSE Linux Installer: sudo rpm -i NeurodeskApp-Setup-Fedora.rpm
Arch-based package via AUR: yay neurodesk (or follow instructions here)
macOS Installer: Double click the downloaded dmg file, then drag the NeurodeskApp.app to the Applications folder; for starting the app: Right click on the NeurodeskApp.app and select “Open”. For Apple Silicon systems (M1/M2): Make sure to enable Rosetta support in the docker settings for best performance!
Windows Installer: Double click the downloaded exe file; Accept to install from an unknown publisher with Yes; then accept the license agreement and click finish at the end.

Launching Neurodesk App

The Neurodesk App can be launched directly from your operating system’s application menu, or by running the neurodeskapp command in the command line.

Note that the Neurodesk App will set the File Browser’s root directory based on the launch method used. The default working directory is the user’s home directory - this can be customized from the Settings dialog.

Sessions and Projects

Sessions represent local project launches and connections to existing Neurodesk servers. Each Neurodesk UI window in the app is associated with a separate session and sessions can be restored with the same configuration later on.

Session start options

You can start a new session by using the links at the Start section of the Welcome Page.

Open Local Neurodesk.. creates a new session in the default working directory.
Connect to remote Neurodesk server.. creates a session by connecting to a remote Neurodesk server.

Previously opened sessions are stored as part of application data and they are listed on the Welcome Page. Clicking an item in the Recent sessions list restores the selected session.

Connecting to local Neurodesk

Neurodesk App creates new Neurodesk sessions by launching a locally running Neurodesk server and connecting to it. To open a local instance, click the Open Local Neurodesk.. button in the Start section of the Welcome Page.

This will show a Jupyterlab interface. There are two options to interact with Neurodesk through this interface:

By clicking the NeurodeskApp icon on the right. This will launch a new window to start a Neurodesk interface.
By module loading containers on the left bar. You can interact with loaded modules through the command line interface.

Connecting to a remote Neurodesk Server

It can also connect to an existing Neurodesk server instance that is running remotely. In order to connect to a server, click the Connect to remote Neurodesk server.. button in the Start section of the Welcome Page.

This will launch a dialog that automatically lists the remote Neurodesk server instances.

Select a server from the list or enter the URL of the Neurodesk application server. If the server requires a token for authentication, make sure to include it as a query parameter of the URL as well (/lab?token=<token-value>). After entering a URL hit Enter key to connect.

If the Persist session data option is checked, then the session information is stored and Neurodesk App will re-use this data on the next launch. If this option is not checked, the session data is automatically deleted at the next launch and servers requiring authentication will prompt for re-login.

You can delete the stored session data manually at any time by using the Clear History option in the Privacy tab of Settings dialog.

Settings privacy tab showing Clear History option

Configuration and data files

Neurodesk App stores data in ~/neurodesktop-storage for Linux and Mac, or C:/neurodesktop-storage for Windows, as default.

Add a Custom Data Directory

Neurodesk App stores its data in the following locations:

By default, /home/jovyan/neurodesktop-storage in the app (which is bound with local directory ~/neurodesktop-storage in Unix/MacOS or C:/neurodesktop-storage in Windows)
By choice, in the settings window below, select Additional Directory on the left side bar, click Change button to select the local directory, then click Apply & restart. The next time you start the app, the data from the local directory can be found in /home/jovyan/data.

If you are using Windows it is currently not possible to mount external hard drives. We recommend copying data from the external drive to your local disk first and then processing it in Neurodesk.

If you are using MacOS and Docker mounting an external hard drive will work out of the box. If you are using Podman you have to modify the Podman machine settings with the following commands once and then set the path in the Neurodesk App:

podman machine reset -f   
podman machine init --rootful --now -v /Volumes:/Volumes -v $HOME:$HOME podman-machine-default

If you are using conda environments and you are installing packages or even new kernels, make sure to read this: https://neurodesk.org/tutorials-examples/tutorials/programming/conda/

Troubleshooting Neurodesk App

/var/run/docker.sock: connect: permission denied, docker

This means that docker is not correctly setup yet, run:

sudo groupadd docker
sudo usermod -aG docker $USER
newgrp docker

sudo chown root:docker /var/run/docker.sock
sudo chmod 666 /var/run/docker.sock

FATAL:setuid_sandbox_host.cc(158)

If you see the error “FATAL:setuid_sandbox_host.cc(158)] The SUID sandbox helper binary was found, but is not configured correctly. Rather than run without sandboxing I’m aborting now. You need to make sure that /opt/NeurodeskApp/chrome-sandbox is owned by root and has mode 4755. Trace/breakpoint trap (core dumped)” this is caused by a recent change in Ubuntu 24.04.

A temporary workaround: Create the file /etc/apparmor.d/neurodeskapp With this content:

# This profile allows everything and only exists to give the
# application a name instead of having the label "unconfined"

abi <abi/4.0>,
include <tunables/global>

profile neurodeskapp "/opt/NeurodeskApp/neurodeskapp" flags=(unconfined) {
  userns,

  # Site-specific additions and overrides. See local/README for details.
  include if exists <local/neurodeskapp>
}

Then restart your computer. Then try to start the neurodesk app again.

Uninstalling Neurodesk App

Debian, Ubuntu Linux

sudo apt-get purge neurodeskapp # remove application
sudo rm /usr/bin/neurodeskapp # remove command symlink
rm -rf ~/.config/neurodeskapp # to remove application cache

Red Hat, Fedora, SUSE Linux

sudo rpm -e neurodeskapp # remove application
sudo rm /usr/bin/neurodeskapp # remove command symlink
rm -rf ~/.config/neurodeskapp # to remove application cache

Arch-based Linux distributions

sudo pacman -Rs neurodeskapp-bin

macOS

Find the application installation NeurodeskApp.app in Finder (in /Applications or ~/Applications) and move to Trash by using CMD + Delete. Clean other application generated files using:

rm -rf ~/Library/neurodeskapp # to remove application cache
rm -rf ~/Library/Application\ Support/neurodeskapp # to remove user data

Windows

On Windows, go to Windows Apps & Features dialog using Start Menu -> Settings -> Apps and uninstall Neurodesk App as shown below.

In order to remove application cache, delete C:\Users\<username>\AppData\Roaming\neurodeskapp directory. The AppData directory is a hidden directory - so make sure to activate hidden Items in the Windows explorer under View -> Show -> Hidden Items