TotalSegmentator v2.15.0: Deploy CT Body Segmentation

Two ways to deploy TotalSegmentator for CT whole body segmentation: pip into a Python env, or pull the Docker image. Most tutorials pick pip and stop there. Wrong call if you’re on a shared server or building a research pipeline.

Docker (wasserth/totalsegmentator:2.2.1) locks the CUDA/PyTorch/nnU-Net stack – nothing in your environment can touch it. Pip is faster to try, but you inherit every version conflict on the box. TotalSegmentator is unusually picky about PyTorch versions (more on that in a moment). Shared server with other ML code already installed? Docker. Fresh conda env on your own workstation? Pip is fine. That’s the whole decision.

Note: the Docker image tag (2.2.1) and the pip package version (2.15.0) follow independent versioning schemes – the Docker tag isn’t behind, they just track separately. As of July 2026, v2.15.0 is the current pip release on PyPI.

What you’re actually installing

TotalSegmentator is a CLI built on a custom nnU-Net fork. It segments 117+ anatomical structures in CT scans – bones, organs, vessels, muscles – with expanding MR support as of mid-2026. Wasserthal et al. at University Hospital Basel published the method; it’s Apache 2.0 licensed. And yes – not a medical device.

117 structures sounds like a lot. In practice, most pipelines only ever invoke a handful – liver, spleen, aorta, maybe vertebrae. The rest exist for the rare study that needs them. Worth knowing before you assume you’ll use all of them.

The pip package itself is small (~10 MB). The weight files land in ~/.totalsegmentator on first run and can get large depending on how many tasks you invoke – plan disk space accordingly.

System requirements

The PyTorch ceiling is the part that trips people. Per the install documentation, versions 2.6+ are unsupported. A bare pip install torch today pulls something newer. The tool will either fail on import or crash mid-prediction – no clear error about the version mismatch.

Install step by step

Fresh conda env first. This keeps the PyTorch pin isolated.

# 1. Create isolated env
conda create -n totalseg python=3.11 -y
conda activate totalseg

# 2. Install PyTorch pinned to supported range
# (adjust CUDA suffix: cu118, cu121, or cpu)
pip install "torch>=2.0,<2.6" --index-url https://download.pytorch.org/whl/cu121

# 3. Install TotalSegmentator
pip install TotalSegmentator

# 4. Verify
TotalSegmentator --version

Step 4 prints a version string – the CLI works. No weights yet. Those download the first time you actually segment something.

Docker alternative:

docker run --gpus 'device=0' --ipc=host 
 -v /absolute/path/to/data:/tmp 
 wasserth/totalsegmentator:2.2.1 
 TotalSegmentator -i /tmp/ct.nii.gz -o /tmp/segmentations

First-time configuration

Before your first real scan, run totalseg_info – it reads the capability registry without touching the GPU or downloading anything:

totalseg_info --list-tasks
totalseg_info --classes -ta total

Then a real segmentation. The --fast flag uses a lower-resolution model and much less memory. Run it first – find out about problems in 2 minutes, not 45.

TotalSegmentator -i ct.nii.gz -o seg_output --fast

Config lives at ~/.totalsegmentator/config.json. To disable anonymous usage stats, flip send_usage_stats to false.

Deploying on an air-gapped machine – common in hospital environments? Install on an internet-connected machine, run one segmentation to pull the weights, then copy the entire ~/.totalsegmentator folder to the offline box. Turns out this is the official procedure from the README, just buried well enough that most guides skip it entirely.

Errors you’ll actually hit

Three issues dominate the support threads. None of them have obvious error messages.

• RuntimeError: CUDA out of memory – The fix isn’t a smaller batch size; there’s no exposed batch flag. Per SlicerTotalSegmentator troubleshooting, the threshold is 7 GB of free VRAM. Below that: free the GPU, drop to --fast, or reinstall PyTorch with the cpu backend. Those are the three options.
• ITK only supports orthonormal direction cosines – A weird affine in your input NIfTI, usually from a botched DICOM→NIfTI conversion or an oblique acquisition. Re-convert with dcm2niix or resample so the direction matrix is orthonormal.
• UserWarning: Detected old nnU-Net plans format – Logged in GitHub issue #306. Looks fatal. It’s not – the tool self-recovers. If segmentation still fails after this warning, the real error is elsewhere in the log.

One more: a pre-existing nnU-Net install will silently break things. TotalSegmentator ships a custom fork, and the two fight. If you had nnU-Net installed before, uninstall it (pip uninstall nnunetv2) and reinstall TotalSegmentator in a clean env.

Upgrading and uninstalling

pip install --upgrade TotalSegmentator

Weights are stored separately from the code, so a version bump won’t re-download everything – only models that changed. One thing to check after an upgrade: if a task you relied on behaves differently, the weights for that task may have been updated silently.

Full removal:

pip uninstall TotalSegmentator nnunetv2
rm -rf ~/.totalsegmentator

That last line – deleting ~/.totalsegmentator – is the one people forget. The weights folder can grow large depending on how many tasks you’ve run.

The two GitHubs

Search results surface both wasserth/TotalSegmentator and StanfordMIMI/TotalSegmentatorV2. Install from PyPI or the wasserth repo – that’s where new weights land first. The Stanford fork mirrors v2 and is useful as a reference, but it’s not the upstream.

FAQ

Can I skip the GPU entirely?

Yes. Use --fast or --roi_subset – full-resolution CPU inference runs 40-50 minutes per scan.

Does it handle DICOM directly, or do I need NIfTI?

The official documentation doesn’t explicitly confirm DICOM folder input for all recent versions – check the current README before assuming. For any pipeline you’ll run repeatedly, converting to NIfTI with dcm2niix first is safer: it gives you one place to catch geometry problems (the orthonormal-direction error above shows up almost exclusively on DICOM inputs from oblique acquisitions) before they reach the segmentation step and fail silently mid-run.

Is v2.15.0 safe for production research, or should I pin an older version?

Pin it. Reproducibility in medical imaging research means the exact same weights and code every time. Add TotalSegmentator==2.15.0 to your requirements.txt and archive the ~/.totalsegmentator weights folder alongside your data. “Latest” today will not be “latest” six months into your study – model weights can update between versions, and results may shift in ways that are difficult to trace after the fact.

Next step: spin up a fresh conda env, run the four install commands above, and try TotalSegmentator -i your_ct.nii.gz -o out --fast --roi_subset liver spleen. Two masks in under 5 minutes means you’re deployed.