ANTsPy: registration and segmentation for medical images from Python

The problem: the algorithms exist, the interface does not

Medical image analysis has a split personality. The algorithms that work are often twenty years old, written in C++ by people who needed them to run on a cluster. The people who want to use them today are Python programmers with a pandas dataframe and a Jupyter notebook.

ANTsPy is the bridge. It wraps the well-established C++ biomedical image processing framework ANTs, and it includes fast reading and writing of medical images, algorithms for registration, segmentation and statistical learning, and functions to create publication-ready visualisations. The name is the acronym, Advanced Normalization Tools in Python, and the paper is open access on PubMed.

The audience is broad for a scientific library: neuroimaging researchers, imaging scientists, and anyone who has an MRI or CT series and needs to align two volumes, pull out a structure, or produce a figure for a paper. The package description calls it a fast medical imaging analysis library in Python with algorithms for registration, segmentation and more.

Two things are worth knowing before you install anything. First, this is a binding, not a reimplementation, so what you get is the behaviour of the underlying C++ toolkit with a Python surface on it, and the project is explicit that contributors need to understand how the project wraps ITK and ANTs code in C++. Second, there is a companion project for a different job: if you are looking to train deep learning models on medical imaging datasets, the documentation points you at ANTsPyNet instead, which provides tools for training and visualising deep learning models.

The licence is Apache-2.0, the repository is not archived, and the last push was on 2026-10-16.

The mechanism: nanobind, scikit-build-core and CMake

How the binding is built is visible in the packaging metadata, and it explains the shape of the install.

The build backend is scikit-build-core, with a requirement of 0.4.3 or newer, and the Python side of the binding is generated by nanobind, pinned to a range of 1.3.2 up to but not including 2.6. The project configuration says the minimum scikit-build-core version is 0.4, with a comment that this protects the configuration against future changes in scikit-build-core, and it sets a build directory of build/{wheel_tag} for setuptools-style build caching in a local directory.

The wheel packages list is:

wheel.packages = ["ants"]

That single line explains the naming that trips people up. The distribution on PyPI is antspyx, and the import is:

import ants

There is also a CMakeLists.txt at the root of the repository, because the C++ side is a CMake project, and the Docker build drives that same toolchain. The Python dependency set is scientific rather than exotic: pandas, numpy with an upper bound of 2.4.0, scipy, statsmodels, matplotlib, requests and scikit-learn, which is also what requirements.txt lists.

The consequence for a user is that ANTsPy behaves like a compiled extension module. It carries platform specific wheels, it has a build step when a wheel is missing, and it inherits the constraints of whatever C++ toolchain and ITK version it was built against.

Installing: wheels, conda, and the gaps in between

The easy way to install ANTsPy is the pre-compiled binary from PyPI:

pip install antspyx

or from conda:

conda install conda-forge::antspyx

Two caveats follow directly from how the project publishes. The first is coverage: because of limited storage space, pip binaries are not available for every combination of Python version and platform, and older releases have been deleted to make space. The workaround the project offers is the Releases page on GitHub, which carries archived binaries, so a combination that is no longer on PyPI may still be installable from a release artefact.

The second caveat is macOS, and it is a specific failure mode. Some macOS Python installations have compatibility issues with the pre-compiled binaries, which means pip will not install binaries targeted for the current macOS version and will instead try to compile from source. The compatibility checks can be disabled by setting the environment variable SYSTEM_VERSION_COMPAT=0, and the project links a wiki page on macOS wheel compatibility issues for the detail.

Windows has its own requirement, a compatible Microsoft Visual C++ Redistributable installation, which makes sense for a package that links a large native library.

Building from source is the fallback, and the documentation notes that in general you can build ANTsPy as you would any other Python package:

git clone https://github.com/antsx/antspy
cd antspy
python -m pip install .

The clone URL in the documentation uses the lowercase antsx/antspy path while the repository itself is ANTsX/ANTsPy, which is a small thing to notice before you conclude that a clone has failed.

The Docker build and the cross-architecture story

The Dockerfile is where the project's release engineering shows, and it is unusual enough to be worth reading.

The comment at the top says the Dockerfile supports amd64, arm64 and ppc64le, and warns that a QEMU emulated ppc64le build might take about six hours. That single line tells you that the project publishes binaries for a supercomputer architecture, and that it does so by emulating the target during the build.

The build stage starts from debian:trixie, installs a toolchain including build-essential, libpng-dev and wget, and then downloads Miniforge3 to get mamba, which the comment explains is used to resolve dependencies cross-platform. The environment is then updated from environment.yml, cmake is installed, the package is installed with pip, and the tests are run in the image:

RUN bash tests/run_tests.sh

The final stage is debian:trixie-slim with the conda installation copied in, so the runtime image carries the resolved environment rather than the build toolchain.

The wheel configuration in pyproject.toml mirrors the same discipline. cibuildwheel is configured with build-verbosity set to 1 so the actual compilation output is visible, and the test command runs pytest against the project tests, with pytest as a test requirement, so a wheel is not published without the test suite having run against it.

There is a published container image, antsx/antspy, with a Docker pulls badge, plus workflows for nightly wheels, pytest and the Docker build, and a coverage badge, so the release path is reasonably well instrumented.

The quickstart: images as first class objects

The quickstart in the repository is worth reading as an API description, because the design decision is visible in it: an image is an object with operators, not a bare array.

import ants

# read / write images
img = ants.image_read('path/to/image.nii.gz')
ants.image_write(img, 'path/to/image.nii.gz')

# basic operations
img + img2
img - img2
img[:20,:20,:20] # indexing returns an image

# advanced operations
img = ants.smooth_image(img, 2)
img = ants.resample_image(img, (3,3,3))
img.smooth_image(2).resample_image((3,3,3)) # chaining

# convert to or from numpy
arr = img.numpy()
img2 = ants.from_numpy(arr * 2)

# segmentation
result = ants.atropos(a=img, m='[0.2,1x1]', c='[2,0]', i='kmeans[3]', x=ants.get_mask(img))

# registration
result = ants.registration(fixed_image, moving_image, type_of_transform = 'SyN' )

# plotting
ants.plot(img, overlay = img > img.mean())

Four things stand out. Arithmetic on images returns an image, and slicing an image returns an image, so the array semantics you already know survive. Operations chain, with smooth_image and resample_image composed in one expression. The numpy interop is explicit rather than implicit, through img.numpy and ants.from_numpy, which is the right way to do it, since it makes the boundary between the C++ object and the Python array explicit in the code. And the two heavyweight operations, atropos for segmentation and registration with a SyN transform, are named calls with the algorithm parameters as ordinary Python arguments, which is how you use a well-established scientific toolkit rather than a thin demo.

The import name is ants, the file format shown is NIfTI with gzip, and the plotting helper is there for the figure at the end of the paper.

Tutorials, and how the project expects contributors to work

Learning resources live in a tutorials directory, and the selection linked from the documentation is a good guide to what the library is used for: a five minute basic overview, composite registrations, multi-metric registration, image math operations, and a page on wrapping ITK code. The composite and multi-metric registration notebooks are the ones that matter for anyone doing serious work, because a single registration with one similarity metric is a solved problem and real datasets need the harder variants.

The contributing guidance is honest about the difficulty. The documentation says the best way to get help is a GitHub issue, welcomes contributions, and points new contributors at a contributors guide that runs through the structure of the project and how the team goes about wrapping ITK and ANTs code in C++. So the expectation is clear: adding a function to ANTsPy is not a Python exercise, it is a C++ and binding exercise, and the guide is the place to start.

That expectation is a strength for a library whose value depends on the fidelity of the wrapper. A binding that quietly approximates the original algorithm is worse than no binding, because the user has no way to tell. The reference material is also unusually well signposted: the main references live in the ANTs repository, and the documentation links to Google Scholar searches for both the community's work and the authors' own.

The project also asks for citation and visibility, which is normal for a scientific library, and the repository carries a Contributor Covenant badge and a code of conduct file.

Licence, versions and where ANTsPy is the wrong choice

The licence is Apache-2.0, declared in the project metadata with the text of the licence in the LICENSE file, and the classifier records it as the Apache Software License. For an academic and industrial research library, that is the permissive and uncontroversial choice, and it is also the licence the underlying ANTs project uses, which keeps the chain clean for anyone combining the two.

The release history has an unusual shape that is worth knowing before you pin. The published versions are v0.6.3, named Alibertia, from 2026-02-23, v0.6.2, Alfaroa, from 2026-01-20 and v0.6.1, Aiouea, from 2025-06-25. Meanwhile the project metadata in the tree already says version 0.6.4, so the working tree is ahead of the last tag by a patch. The naming scheme with a codename per release also means the version alone does not tell you what changed, and the changelog is the place to look.

The wrong-choice cases are specific. If you need to train a deep learning model on medical images, this is the wrong library, because that is ANTsPyNet's job. If you need a guaranteed wheel for your exact interpreter and platform, the coverage gaps and the deletion of old releases make the archived releases page a mandatory stop rather than an optional one. And if you want an image processing library that does not carry a large native C++ dependency, the pip install can turn into a source build that needs a working toolchain, ITK and a long compile, which is a different maintenance commitment from a pure Python package.

For everything else, the honest summary is that ANTsPy is a mature binding with a published paper, a wheel pipeline that runs its own tests, a container image that builds for three architectures, and an API where an image behaves like an object. What it is not is a new set of algorithms, and a reader should evaluate it on the strength of the C++ framework underneath it.

Editorial conclusion

Adopt ANTsPy if you need image registration or segmentation on medical data and want the ANTs algorithms from Python rather than from a C++ program you have to link against. Do not adopt it if you need a deep learning training pipeline, since that is a separate project, or if you need a guaranteed wheel for your exact Python and platform combination. Before you install, check the archived releases page for a binary matching your interpreter, because the project deletes older wheels to save storage, and read the macOS compatibility note if pip tries to compile from source instead of installing a wheel.

Frequently asked questions

Official sources

1. ANTsX/ANTsPy on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases