Containers

fsatlas ships as a pre-built container image based on freesurfer/freesurfer:8.0.0. Use it to run fsatlas without installing FreeSurfer locally.

Apptainer is recommended for HPC and cluster environments. Docker works well on local workstations.

---

Apptainer / Singularity

Apptainer (formerly Singularity) is the standard container runtime on most HPC clusters. It runs containers as an unprivileged user, mounts the host filesystem automatically, and integrates well with SLURM and PBS schedulers.

Pull the image

apptainer pull fsatlas.sif docker://galkepler/fsatlas:latest

Or build from source (requires the repository):

apptainer build fsatlas.sif apptainer.def

Basic usage

apptainer run \
    --bind /path/to/SUBJECTS_DIR:/subjects \
    --bind /path/to/license.txt:/license.txt:ro \
    --env SUBJECTS_DIR=/subjects \
    fsatlas.sif \
    --freesurfer-license-file /license.txt \
    extract --atlas schaefer100-7 -o /subjects/results

License via environment variable

export FS_LICENSE=/path/to/license.txt

apptainer run \
    --bind /path/to/SUBJECTS_DIR:/subjects \
    --env SUBJECTS_DIR=/subjects \
    --env FS_LICENSE=/path/to/license.txt \
    fsatlas.sif \
    extract --atlas schaefer100-7 -o /subjects/results

List available atlases

apptainer run \
    --bind /path/to/license.txt:/license.txt:ro \
    fsatlas.sif \
    --freesurfer-license-file /license.txt \
    list-atlases

Persist the atlas cache

Apptainer mounts $HOME automatically, so ~/.cache/fsatlas/ is accessible by default. If you prefer an explicit bind:

apptainer run \
    --bind /path/to/SUBJECTS_DIR:/subjects \
    --bind $HOME/.cache/fsatlas:/root/.cache/fsatlas \
    --env SUBJECTS_DIR=/subjects \
    fsatlas.sif \
    --freesurfer-license-file /license.txt \
    extract --atlas schaefer400-17 -o /subjects/results

SLURM example

#!/bin/bash
#SBATCH --job-name=fsatlas
#SBATCH --cpus-per-task=4
#SBATCH --mem=16G
#SBATCH --time=12:00:00

apptainer run \
    --bind $SUBJECTS_DIR:/subjects \
    --bind $FS_LICENSE:/license.txt:ro \
    --env SUBJECTS_DIR=/subjects \
    /path/to/fsatlas.sif \
    --freesurfer-license-file /license.txt \
    extract \
        --atlas schaefer400-17 \
        --subjects-file subjects.txt \
        -o /subjects/fsatlas_output

---

Docker

Pull the image

docker pull galkepler/fsatlas:latest

Or build from source:

docker build -t fsatlas .

Basic usage

docker run --rm \
    -v /path/to/SUBJECTS_DIR:/subjects \
    -v /path/to/license.txt:/opt/freesurfer/license.txt \
    -e SUBJECTS_DIR=/subjects \
    galkepler/fsatlas:latest \
    extract --atlas schaefer100-7 -o /subjects/results

With a separate output directory

docker run --rm \
    -v /data/subjects:/subjects \
    -v /data/license.txt:/opt/freesurfer/license.txt \
    -v /data/results:/results \
    -e SUBJECTS_DIR=/subjects \
    galkepler/fsatlas:latest \
    extract --atlas tian-s2 -o /results

Examples

List available atlases

docker run --rm \
    -v /path/to/license.txt:/opt/freesurfer/license.txt \
    galkepler/fsatlas:latest \
    list-atlases

Extract Schaefer 400 for specific subjects

docker run --rm \
    -v /data/subjects:/subjects \
    -v /data/license.txt:/opt/freesurfer/license.txt \
    -v /data/results:/results \
    -e SUBJECTS_DIR=/subjects \
    galkepler/fsatlas:latest \
    extract \
        --atlas schaefer400-17 \
        -s sub-01 -s sub-02 -s sub-03 \
        -o /results

Pre-download an atlas (then run offline)

# Download to host cache
docker run --rm \
    -v $HOME/.cache/fsatlas:/root/.cache/fsatlas \
    -v /path/to/license.txt:/opt/freesurfer/license.txt \
    galkepler/fsatlas:latest \
    download schaefer400-17

# Run offline, reusing cache
docker run --rm \
    -v /data/subjects:/subjects \
    -v /data/license.txt:/opt/freesurfer/license.txt \
    -v $HOME/.cache/fsatlas:/root/.cache/fsatlas \
    -v /data/results:/results \
    -e SUBJECTS_DIR=/subjects \
    --network none \
    galkepler/fsatlas:latest \
    extract --atlas schaefer400-17 -o /results

Custom atlas

docker run --rm \
    -v /data/subjects:/subjects \
    -v /data/license.txt:/opt/freesurfer/license.txt \
    -v /data/atlases:/atlases \
    -v /data/results:/results \
    -e SUBJECTS_DIR=/subjects \
    galkepler/fsatlas:latest \
    extract \
        --atlas /atlases/lh.myatlas.annot \
        --lut /atlases/myatlas_lut.tsv \
        -o /results

---

Key Mount Points

Host path	Container path	Purpose
$SUBJECTS_DIR	/subjects	FreeSurfer subjects directory
/path/to/license.txt	/opt/freesurfer/license.txt (Docker) or via --freesurfer-license-file	FreeSurfer license (required)
~/.cache/fsatlas	/root/.cache/fsatlas	Atlas download cache (optional)
Output directory	/results	Results (optional separate mount)

---

Notes

FreeSurfer License Required

A valid FreeSurfer license (license.txt) must be provided. Licenses are free for academic use — register at the FreeSurfer website.

For Apptainer, pass it with --freesurfer-license-file /path/to/license.txt or set FS_LICENSE. For Docker, mount it at /opt/freesurfer/license.txt.

Atlas Cache Persistence

To avoid re-downloading atlases on every container run, persist the cache directory:

• Apptainer: $HOME is mounted automatically; ~/.cache/fsatlas/ is available by default.
• Docker: Add -v $HOME/.cache/fsatlas:/root/.cache/fsatlas.

Memory

Processing large cohorts or high-resolution atlases may require significant memory. For Docker Desktop, increase the memory limit in settings. For SLURM, adjust --mem.