TorchIO: medical image augmentation that respects voxel spacing
Medical imaging processing for AI applications.
At a glance
- What is it?
- TorchIO is a Python library for loading, transforming and augmenting 3D medical images in PyTorch pipelines. Its value is that spatial transforms operate on the image geometry, not just the array, which is the part most generic augmentation libraries get wrong.
- Who is it for?
- Adopt TorchIO if your training data is volumetric medical imaging with real voxel spacing and affine metadata, and you are already inside a PyTorch pipeline. Do not adopt it if you only have 2D natural images, or if your labels are per-slice and you have no intention of moving to 3D.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 45 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem TorchIO addresses: augmentation that ignores scanner geometry
Generic image augmentation libraries treat a picture as a grid of pixels. Medical volumes are not that. A CT or MRI study arrives as a NIfTI file with voxel spacing, an origin and a direction matrix, and those numbers differ between scanners, protocols and sites. If you rotate a volume with a library that only knows about array indices, the resulting image no longer corresponds to any physically plausible acquisition. The label mask may rotate with it, but the spacing metadata does not, and any downstream step that resamples or compares volumes is now working with numbers that describe a different object than the one in the array.
TorchIO is aimed at researchers and engineers training deep learning models on volumetric medical data, which the README describes as medical imaging processing for AI applications. The repository topics list augmentation, data-augmentation, deep-learning and medical-image-analysis alongside PyTorch. The target user is someone who already has a PyTorch training loop and needs the input side of it to behave like a scanner rather than like a photo editor.
Images and transforms: how the geometry survives a random affine
The central abstraction visible in the documentation is the image object, which wraps the tensor together with its affine. Transforms are applied to that object rather than to a bare tensor, so a spatial operation updates the affine alongside the voxel data. That is the mechanism that separates TorchIO from a plain tensor augmentation pipeline, and it is why the library can offer transforms such as RandomAffine and RandomElasticDeformation that are meaningful in physical space.
The README shows a gallery of exactly these: RandomBlur, RandomFlip, RandomNoise, RandomAffine and RandomElasticDeformation, each rendered as an animated GIF on an MRI volume, with links into the augmentation documentation. There is also a separate progressive artifacts animation, which points at a class of augmentation specific to imaging: simulating the degradation a scan accumulates during acquisition rather than perturbing a clean image after the fact. Intensity transforms like blur and noise do not need geometry, but they sit in the same Compose pipeline, which the README illustrates with a combined example.
What the material does not show is the internal implementation of the affine update, so the exact resampling behaviour for non-identity direction matrices cannot be confirmed from what is provided here. The documentation site at docs.torchio.org is where that would need to be checked.
Installing TorchIO from PyPI or conda-forge
The README carries both a PyPI badge and a conda-forge badge, so the package is distributed through both channels. The conventional install is a single pip command against the PyPI name:
pip install torchio
For conda users, the badge points at the conda-forge channel, and the package name there is also torchio:
conda install -c conda-forge torchio
The repository also ships a tutorials directory with a Google Colab badge, which the README links from the Tutorials row of its badge table. That is the lowest-friction way to see the transform API in a working notebook without setting up a local environment. Because the package depends on PyTorch, expect the install to pull or require a matching torch build; the README does not state a version constraint, so that has to come from the package metadata on PyPI.
No configuration file, environment variable or CLI entry point appears in the supplied material. TorchIO is used as an imported library, not as a command line tool.
The 2.0.0 alpha series is not the version to pin
The release list shows v2.0.0a2 and v2.0.0a1, both dated 2026-07-20, followed by v1.2.1 on 2026-06-02. The stable line is 1.2.1. The 2.0.0 releases are alphas, which by convention means the API is still moving and breaking changes between alpha builds are expected rather than exceptional.
This matters for anyone writing a training pipeline they intend to reproduce later. If you install without a version pin, you may end up on an alpha, and a transform signature that worked in one alpha may not survive into the next. Pin to the 1.2.x line for production work and treat 2.0.0a2 as something to evaluate in a separate environment. The repository does not indicate in the supplied material what changed between 1.2.1 and 2.0.0a1, so the migration cost of moving to 2.0.0 cannot be estimated from this material alone. Check the release notes on the repository before planning that upgrade.
A second limitation is structural rather than version-related. TorchIO assumes your data is volumetric and carries geometry. If your dataset is a folder of 2D PNGs with no spacing information, the image abstraction adds a layer of metadata you are not using, and a plain torchvision or albumentations pipeline will be less code for the same result. TorchIO is the wrong tool when the geometry does not exist to begin with.
Where TorchIO sits relative to MONAI and to plain torchvision
MONAI is the obvious comparison, since it also targets deep learning for medical imaging and also builds on PyTorch. The difference in approach is scope. MONAI covers transforms, network architectures, losses, metrics and inference workflows in one package. TorchIO, based on what the README and topics describe, is concentrated on the input pipeline: loading, preprocessing and augmentation of images and their labels. If you want a batteries-included medical imaging framework, MONAI is the broader choice. If you already have a model, a loss and a training loop you are happy with, and the only thing missing is geometry-aware augmentation, TorchIO is the smaller dependency to add.
Against torchvision transforms, the difference is more fundamental. torchvision operates on tensors and PIL images with no concept of voxel spacing or affine matrices, which is fine for natural images and inadequate for volumes where a flip along the wrong physical axis changes the meaning of the data. The trade-off TorchIO makes is that you must carry its image object through your dataset and dataloader rather than passing raw tensors. That is extra plumbing, and it is the price of the geometry handling.
Licence and long-term maintenance signals
TorchIO is released under Apache-2.0. That is a permissive licence with an explicit patent grant, which is generally the reason projects in regulated or commercial medical contexts pick it over a copyleft option. It does not impose a copyleft obligation on your own code. This is a description of the licence identifier, not legal advice; if you are shipping a regulated device or a commercial product, have your own counsel read the terms rather than relying on a summary.
The maintenance signals in the supplied material are mixed in a way worth stating plainly. The repository is not archived, and the last push date is 2026-08-01, which is recent relative to the 1.2.1 release in June 2026. There is active CI, with separate workflows for tests and documentation, and a coverage badge. There is also an all-contributors badge and a linked YouTube talk in the community row. What the material does not give is a contributor count, a release cadence history, or a roadmap. The presence of a 2.0.0 alpha series suggests active development rather than maintenance-only mode, but the alpha numbering also means the next major version is not finished. Plan for the 1.2.x line to be what you depend on for now.
What to check before you build on it
The first thing to verify is your own data, not the library. TorchIO's spatial transforms are defined on the affine stored in your image headers. If your NIfTI files were converted carelessly from DICOM, or exported from a tool that wrote an identity affine, then every random affine and elastic deformation you apply will be geometrically wrong in a way that is invisible in the augmented images. Load a few volumes, print the affine and the spacing, and confirm they match the acquisition you expect. This is a five minute check that prevents a silent data quality problem across an entire training run.
The second thing to verify is which version you are actually installing. Run pip show torchio after install and confirm you got 1.2.x rather than a 2.0.0 alpha pulled in by a resolver. The third is whether the progressive artifacts transform matches the degradation you see in your own scans, since the README links that animation directly to the augmentation documentation and it is the feature least likely to have an equivalent in a general purpose library.
If those three checks pass, TorchIO is a narrow, well-scoped addition to a PyTorch medical imaging pipeline. If the first one fails, no augmentation library will save the experiment.
Editorial conclusion
Adopt TorchIO if your training data is volumetric medical imaging with real voxel spacing and affine metadata, and you are already inside a PyTorch pipeline. Do not adopt it if you only have 2D natural images, or if your labels are per-slice and you have no intention of moving to 3D. Before committing, verify one thing first: that your NIfTI headers carry correct affine matrices, because TorchIO's spatial transforms are defined on that geometry and will faithfully propagate whatever is wrong in your headers into your augmented training set.
Community notes