macOS

Quickstart

Install Docker or Podman

Install Docker from the Docker install docs. Alternatively, Neurodesk also works with Podman: follow the Podman installation instructions.

Caution

Docker for macOS by default runs with 2GB memory. For actual workloads, 4GB memory minimum for Docker is highly recommended. You need to adjust this:

1. Open Docker Desktop and navigate to the Settings. Then navigate to the “Resources” section.
2. Increase the Memory slider from 2.00 GB to 4.00 GB (or greater).
3. Increase the Swap slider from 1GB to 2GB (or greater).

Run Neurodesktop

Use one of the following options to run Neurodesktop:

Neurodesk App (recommended)

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

Terminal

Create a local folder where the downloaded applications will be stored, e.g. ~/neurodesktop-storage.

1. Open a terminal, and type the following command to automatically download the Neurodesktop container and run it.

   docker volume create neurodesk-home &&
   docker run \
   --shm-size=1gb -it --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

   If you get errors in Neurodesktop then check if the ~/neurodesktop-storage directory is writable for all users. If it is not, run chmod a+rwx ~/neurodesktop-storage.

2. 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

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

   Caution

   We recommend using Chrome over Firefox as it has an option to hide the toolbar in full-screen mode (go to the menu bar, click on View, and uncheck “Always Show Toolbar in Full Screen”). This allows Neurodesktop to fully utilise the whole of your screen.

4. If prompted, press on “Desktop RDP - changes resolution by resizing window and waiting for refresh” or “Desktop VNC - changes resolution by running lxrandr on a terminal” under “ALL CONNECTIONS”.

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

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

Note

The browser can be closed anytime, and Neurodesktop will continue to run 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.

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. Type:

   docker stop neurodesktop

4. Type:

   docker rm neurodesktop