Installation

Brainana can be installed in two ways:

  • Docker (below) — full pipeline: anatomical and functional preprocessing, surface reconstruction, and HTML QC reports. This is the recommended path for most users.

  • ✨ Brainana Lite — lightweight volumetric T1w workflow via Jupyter or Colab; no Docker image. See BrainanaLite.ipynb notebook on GitHub and the documentation page Brainana Lite.

Docker

The recommended way to run the full Brainana pipeline is with Docker.

System requirements

Warning

  • Host: Any OS supported by Docker (Linux, macOS, Windows with WSL2)

  • RAM + swap: ≥ 16 GB (recommended 20 GB+ for full pipeline)

  • Disk: ≥ 20 GB (recommended 50 GB+ for multiple subjects)

  • CPU: ≥ 4 logical cores (recommended 8+)

  • GPU (optional, NVIDIA only): ≥ 6 GB VRAM (recommended ≥ 10 GB for production)

  • NVIDIA Driver (optional): ≥ 520.61.05 if using GPU

  • CUDA (optional): ≥ 11.8 if using GPU

Resource guidelines:

  • Minimal: 16 GB RAM, 4 CPUs, 20 GB disk

  • Recommended: 20 GB RAM, 8 CPUs, 50 GB disk, 1 NVIDIA GPU with ≥ 6 GB VRAM

  • Production: 32 GB RAM, 8+ CPUs, 100 GB+ disk, 1 NVIDIA GPU with ≥ 10 GB VRAM

Set up Docker

  1. Install Docker if you do not have it (Docker Installation).

  2. Test Docker with the hello-world image:

    docker run -it --rm hello-world

    You should see a message indicating that Docker is working correctly.

  1. Check GPU access (optional):

    A GPU is compatible if it is NVIDIA and meets the driver and CUDA minimums.

    1. You can check with:

    nvidia-smi

    In the output (top-right corner), check:

    • Driver version — must be ≥ 520.61.05

    • CUDA version — must be ≥ 11.8

    If you have no NVIDIA GPU, or either value is below the minimum, no compatible GPU is available. Skip the rest of this step.

    1. verify Docker can access your GPU:

    docker run -it --rm --gpus all hello-world

    Note

    If you see an error about nvidia-container-cli or libnvidia-ml.so, ensure the NVIDIA Container Toolkit and drivers are installed.

  2. Pull the Brainana image:

    docker pull liuxingyu987/brainana:<version>

    Note

    Replace <version> with a published Brainana tag from Docker Hub, for example 1.2.0. See the Brainana image tags on Docker Hub for the list of available versions.

Once the image is ready, see Usage notes to run the pipeline.