Linux

Minimum system requirements

1. At least 3GB free space for the Neurodesktop base image.
2. Docker requirements (see Docker install docs).

Quickstart

Install Docker or Podman

Install Docker from the Docker install docs. Additional information is available below. Alternatively, Neurodesk also works with Podman.

To set up Neurodesk on Ubuntu, ensure both the Podman client and server are installed. Follow the Podman installation instructions for server setup.

Note

In Ubuntu 20.10 or newer, the packages to install Podman are included in the standard repository of the system. However, for Ubuntu 20.04, we manually have to add the repository of Podman.

sudo apt update && sudo apt upgrade -y
sudo apt install curl
echo "deb https://download.opensuse.org/repositories/devel:/kubic:/libcontainers:/stable/xUbuntu_20.04/ /" | sudo tee /etc/apt/sources.list.d/devel:kubic:libcontainers:stable.list
curl -L "https://download.opensuse.org/repositories/devel:/kubic:/libcontainers:/stable/xUbuntu_20.04/Release.key" | sudo apt-key add -
sudo apt update
sudo apt-get -y install podman

ARM64 hardware?

Neurodesk supports ARM64 through binfmt. Enable it once with:

sudo docker run --privileged --rm tonistiigi/binfmt --install all

Run Neurodesktop

Before the first run, create a local folder where the downloaded applications will be stored, e.g. mkdir ~/neurodesktop-storage.

Choose how you want to run Neurodesktop:

Neurodesk App (recommended)

See the Neurodesk App instructions for installing and using the app.

Terminal

1. If the Linux machine is remote (e.g. in the cloud), connect to the machine with port forwarding first:

   ssh -L 8888:127.0.0.1:8888 USER@IP

2. Then start Neurodesktop:

   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 \
     --add-host=host.docker.internal:host-gateway \
     -e OLLAMA_HOST="http://host.docker.internal:11434" \
     -e NB_UID="$(id -u)" -e NB_GID="$(id -g)" \
     -p 8888:8888 \
     -e NEURODESKTOP_VERSION=2026-04-28 vnmd/neurodesktop:2026-04-28

   Or use the GitHub container registry (in case Docker Hub is down or blocked in your firewall):

   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 \
     --add-host=host.docker.internal:host-gateway \
     -e OLLAMA_HOST="http://host.docker.internal:11434" \
     -e NB_UID="$(id -u)" -e NB_GID="$(id -g)" \
     -p 8888:8888 \
     -e NEURODESKTOP_VERSION=2026-04-28 ghcr.io/neurodesk/neurodesktop/neurodesktop:2026-04-28

   Or for Podman:

   podman volume create neurodesk-home &&
   sudo podman run \
     --shm-size=1gb -it --privileged --user=root --name neurodesktop \
     -v ~/neurodesktop-storage:/neurodesktop-storage \
     --mount type=volume,source=neurodesk-home,target=/home/jovyan \
     -e NB_UID="$(id -u)" -e NB_GID="$(id -g)" \
     -p 8888:8888 \
     -e NEURODESKTOP_VERSION=2026-04-28 docker://vnmd/neurodesktop:2026-04-28

   Caution

   If you run Ubuntu greater than 23.10 you need to create this AppArmor profile under /etc/apparmor.d/neurodeskapp:

   # 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>
   }

   Caution

   If you get errors in Neurodesktop then check if the ~/neurodesktop-storage directory is writable to all users. Otherwise run:

   chmod a+rwx ~/neurodesktop-storage

   Caution

   If you get an error that’s not accessible on your network or causes problems then you can try to use the DNS server 8.8.8.8 (Google Public DNS) in the Docker command:

   docker volume create neurodesk-home &&
   sudo docker run \
     --shm-size=1gb -it --privileged --user=root --name neurodesktop \
     --dns 8.8.8.8 \
     -v ~/neurodesktop-storage:/neurodesktop-storage \
     --mount source=neurodesk-home,target=/home/jovyan \
     --add-host=host.docker.internal:host-gateway \
     -e OLLAMA_HOST="http://host.docker.internal:11434" \
     -e NB_UID="$(id -u)" -e NB_GID="$(id -g)" \
     -p 8888:8888 \
     -e NEURODESKTOP_VERSION=2026-04-28 vnmd/neurodesktop:2026-04-28

3. Once Neurodesktop is downloaded, leave the terminal open and check which server Neurodesktop is running on (avoid pressing Ctrl+C). Look for the URL containing ?token=...:

   [I 2025-04-10 01:49:14.301 ServerApp] Serving notebooks from local directory: /home/jovyan
   [I 2025-04-10 01:49:14.301 ServerApp] Jupyter Server 2.15.0 is running at:
   [I 2025-04-10 01:49:14.301 ServerApp] http://localhost:8888/lab?token=90b9a934f6a76e87e88a9718aada4c6520984694ff853cf2
   
       To access the server, open this file in a browser:
           file:///home/jovyan/.local/share/jupyter/runtime/jpserver-69-open.html
       Or copy and paste one of these URLs:
           http://localhost:8888/lab?token=90b9a934f6a76e87e88a9718aada4c6520984694ff853cf2
           http://127.0.0.1:8888/lab?token=90b9a934f6a76e87e88a9718aada4c6520984694ff853cf2

4. To access Neurodesktop, open your web browser and type in one of the provided URLs in your terminal (e.g. http://127.0.0.1:8888/lab?token=your_unique_token).

   Caution

   If using Chrome, a pop-up may open with the text:

   "http://127.0.0.1:8888 wants to
   See text and images copied to the clipboard".

   Press “Allow” to access your clipboard from within Neurodesktop.

   Caution

   If using Firefox, you might not be able to paste clipboard content into the virtual desktop from the host computer. In that case, please follow these instructions.

5. Press on “Desktop Auto-Resolution” under “ALL CONNECTIONS”.

6. If it is the first time you have used Neurodesktop, wait until the desktop appears (it may take a few seconds). Otherwise, it should appear instantaneously.

7. Neurodesk is now ready to use. See the tutorials page for advice on how to use Neurodesk.

8. For an optimal experience, switch your browser to full-screen mode by following the instructions for your browser.

Note

The browser can be closed anytime, and Neurodesktop will continue running in the background. To reconnect to Neurodesktop, simply start over from step 3 above.

Note

If you are using conda environments and you are installing packages or even new kernels, make sure to read the conda tutorial.

Note

If you want to use Neurodesk in combination with a reverse proxy, make sure to activate proxy_buffering off as described in the Guacamole reverse proxy docs.

Deleting Neurodesktop

When done processing your data it is important to stop and remove the container, otherwise the next start or container update will give an error (”… The container name ‘/neurodesktop’ is already in use…”).

Note

Any data that were saved outside of /neurodesktop-storage would be lost. Please make sure to move all your data to that folder before deleting Neurodesktop.

1. Click on the terminal from which you ran Neurodesktop.

2. Press Ctrl+C.

3. Run:

   docker stop neurodesktop

4. Run:

   docker rm neurodesktop

Installing Docker

For general installation instructions, refer to the Docker install docs.

RHEL / CentOS (yum-based)

Refer to Docker on CentOS.

One example to install Docker in a yum-based distribution could look like this:

sudo dnf install -y yum-utils
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo dnf install docker-ce docker-ce-cli containerd.io
# or if dnf not found: sudo yum install docker-ce docker-ce-cli containerd.io
sudo systemctl enable docker
sudo systemctl start docker
sudo docker version
sudo docker info
sudo groupadd docker
sudo usermod -aG docker $USER
sudo chown root:docker /var/run/docker.sock
newgrp docker

Ubuntu / Debian (apt-based)

Refer to Docker on Ubuntu.

One example to install Docker in an apt-based distribution could look like this:

sudo apt-get update
sudo apt-get install ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update

GPU support

RHEL / CentOS (yum-based)

sudo yum install nvidia-container-toolkit -y

Ubuntu / Debian (apt-based)

sudo apt install nvidia-container-toolkit -y

Running the Neurodesktop container with GPU

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=2026-04-28 \
  vnmd/neurodesktop:2026-04-28

Running TensorFlow (with GPU)

Using TensorFlow (Python)

mamba install tensorflow-gpu
python

import tensorflow as tf
print("Num GPUs Available: ", len(tf.config.list_physical_devices('GPU')))

If TensorFlow can see your GPU, you should see output similar to:

>>> import tensorflow as tf
>>> print("Num GPUs Available: ", len(tf.config.list_physical_devices('GPU')))
2024-01-15 14:22:31.452: I tensorflow/core/platform/cpu_feature_guard.cc:182] This TensorFlow binary is optimized to use available CPU instructions in performance-critical operations.
2024-01-15 14:22:31.821: I tensorflow/core/common_runtime/gpu/gpu_device.cc:1639] Created device /job:localhost/replica:0/task:0/device:GPU:0 with 22308 MB memory:  -> device: 0, name: NVIDIA GeForce RTX 4090, pci bus id: 0000:01:00.0, compute capability: 8.9
Num GPUs Available:  1

Using TensorFlow (singularity container in Neurodesktop)

singularity pull docker://tensorflow/tensorflow:latest-gpu
singularity run --nv tensorflow_latest-gpu.sif
python

import tensorflow as tf
print("Num GPUs Available: ", len(tf.config.list_physical_devices('GPU')))

If the Singularity container can see your GPU, you should see output similar to:

>>> import tensorflow as tf
>>> print("Num GPUs Available: ", len(tf.config.list_physical_devices('GPU')))
2024-01-15 14:25:08.117: I tensorflow/stream_executor/cuda/cuda_gpu_executor.cc:937] successful NUMA node read from SysFS had negative value (-1), but there must be at least one NUMA node, so returning NUMA node zero
2024-01-15 14:25:08.184: I tensorflow/core/common_runtime/gpu/gpu_device.cc:1639] Created device /job:localhost/replica:0/task:0/device:GPU:0 with 22308 MB memory:  -> device: 0, name: NVIDIA GeForce RTX 4090, pci bus id: 0000:01:00.0, compute capability: 8.9
Num GPUs Available:  1