Installation (advanced)
These are more advanced ways to run hippunfold. To simply get started (install using pixi instead).
Conda (Linux/macOS) — more flexible, good for HPC environments, developers.
Containers (Docker or Apptainer/Singularity) — easiest, best for Windows, or when you want fully pinned dependencies.
Note: Containers must be given access to input/output directories by mounting them.
Method |
OS |
Edit code? |
Cluster profiles |
Notes |
|---|---|---|---|---|
Conda |
Linux, macOS |
✅ |
✅ |
Simple, container‑free. Not on Windows. |
Docker |
Windows, Linux, macOS (Intel) |
❌ |
❌ |
Mount paths required; portable. |
Apptainer (Singularity) |
Linux |
❌ |
❌ |
Common on HPC; portable single |
Quickstart (choose one)
Option A — Pixi / Conda / Micromamba (Linux/macOS)
# pixi global install
pixi global install --channel https://prefix.dev/conda-forge --channel https://prefix.dev/akhanf/khanlab --channel https://prefix.dev/bioconda hippunfold
# check it works
hippunfold -h
Conda:
conda config --add channels https://prefix.dev/bioconda
conda config --add channels https://prefix.dev/akhanf/khanlab
conda config --add channels https://prefix.dev/conda-forge
conda install hippunfold
# or
mamba install hippunfold
Micromamba:
micromamba config prepend channels https://prefix.dev/bioconda
micromamba config prepend channels https://prefix.dev/akhanf/khanlab
micromamba config prepend channels https://prefix.dev/conda-forge
micromamba install hippunfold
Run a one‑subject example:
curl -L https://www.dropbox.com/s/mdbmpmmq6fi8sk0/hippunfold_test_data.tar -o hippunfold_test_data.tar
tar -xvf hippunfold_test_data.tar
hippunfold ds002168 ds002168_hippunfold participant --modality T1w --cores all
Option B — Containers (Docker or Apptainer)
Containers share nearly identical commands. Replace docker run with apptainer run depending on your environment. Both need directory mounts to access your data.
1. Pull the container
Docker:
docker pull khanlab/hippunfold:main
Apptainer:
apptainer pull hippunfold_main.sif docker://khanlab/hippunfold:main
2. Dry‑run
# Docker
docker run -it --rm \
-v /directory/to/mount:/data \
khanlab/hippunfold:main \
hippunfold /data/ds002168 /data/ds002168_hippunfold participant --modality T1w -n
# Apptainer
apptainer run -e \
--bind /directory/to/mount:/data \
hippunfold_main.sif \
hippunfold /data/ds002168 /data/ds002168_hippunfold participant --modality T1w -n
3. Run with all cores
# Docker
docker run -it --rm \
-v /directory/to/mount:/data \
khanlab/hippunfold:main \
/data/ds002168 /data/ds002168_hippunfold participant --modality T1w -p --cores all
# Apptainer
apptainer run -e \
--bind /directory/to/mount:/data \
hippunfold_main.sif \
/data/ds002168 /data/ds002168_hippunfold participant --modality T1w -p --cores all
Note on mounting
Docker uses
-v host_path:container_pathApptainer uses
--bind host_path:container_path
To avoid repeating mounts on every command, you can set:
# Apptainer
env APPTAINER_BINDPATH=/project:/project,/data:/data
# Docker (in docker-compose or wrapper scripts)
# e.g., export DOCKER_OPTS="-v /project:/project -v /data:/data"
This way, input/output paths are automatically accessible.
Models & cache (Note)
As of v1.3.0+, containers no longer ship all models; they’re downloaded on demand.
Default cache:
~/.cache/hippunfold
Override with:
export HIPPUNFOLD_CACHE_DIR=/path/to/cache