TorchIO

1.1.0 verified Fri May 01 auth: no python

TorchIO is a Python library for medical image processing with PyTorch, offering data loading, preprocessing, augmentation, and sampling for 3D medical images. Version 1.1.0 requires Python >=3.10. Release cadence is irregular, with multiple minor and patch releases per year.

pip install torchio

Common errors

error ImportError: cannot import name 'SubjectsDataset' from 'torchio' ↓

cause Old import path from torchio.data; torchio v0.18+ moved SubjectsDataset to top-level.

fix

Use 'from torchio import SubjectsDataset' instead of 'from torchio.data import SubjectsDataset'.

error KeyError: 'img' or 'label' not found in Subject when loading from disk ↓

cause Subject expects specific keys for images and labels, but the file may have different naming (e.g., 'image', 'seg').

fix

Ensure the keys in the Subject dictionary match exactly. Use tio.ScalarImage(path) and assign to 'img' key.

error RuntimeError: Expected 4D input but got 3D ↓

cause TorchIO expects batch dimension (B, C, D, H, W) even for single images. Many transforms fail on 3D tensors.

fix

Add a batch dimension: tensor = tensor.unsqueeze(0) or use tio.ScalarImage with shape (1, C, D, H, W).

Warnings

breaking TorchIO v1.0.0 dropped Python 3.7 and 3.8 support. Requires Python >=3.10. ↓

fix Upgrade Python to 3.10 or later, or pin torchio to <1.0.0 if stuck on older Python.

gotcha Transform arguments like 'p' (probability) are now in the range [0,1] for all random transforms, but some older code used percentages. Always pass a float between 0 and 1. ↓

fix Use p=0.5 instead of p=50 for 50% probability.

deprecated The 'image' parameter in Subject constructor is deprecated in favor of 'img'. Using 'image' will raise a warning and may be removed in future versions. ↓

fix Use 'img' instead of 'image' when creating Subject.

Imports

SubjectsDataset
wrong
```
from torchio.data import SubjectsDataset
```
correct
```
from torchio import SubjectsDataset
```
In older versions (pre-0.18), SubjectsDataset was in torchio.data. Now it's exposed at top level.

RandomAffine

wrong

from torchio.transforms import RandomAffine

correct

from torchio import RandomAffine

import from torchio directly is recommended and stable.

Quickstart

Create a minimal Subject with random data and apply transforms.

import torchio as tio
import torch

# Create a subject with a 3D image
subject = tio.Subject(
    img=tio.ScalarImage(tensor=torch.rand(1, 64, 64, 64)),
    label=tio.LabelMap(tensor=torch.randint(0, 2, (1, 64, 64, 64))),
)
print(subject)

# Define a simple transform
transform = tio.Compose([
    tio.RandomAffine(scales=(0.9, 1.2), degrees=10),
    tio.RandomNoise(std=0.1),
])

# Apply transform
transformed = transform(subject)
print(transformed.shape)