NiBabel reads the neuroimaging formats you did not want to write twice

A cacophony of formats, one API on top

The package description says it plainly, a Python package to access a cacophony of neuro-imaging file formats, and the README lists what that means in practice. Read and write access is provided to ANALYZE, in the plain, SPM99 and SPM2 and later variants, GIFTI, NIfTI1, NIfTI2, CIFTI-2, MINC1, MINC2, AFNI BRIK and HEAD, ECAT and Philips PAR and REC. On top of that, NiBabel supports FreeSurfer's MGH, geometry, annotation and morphometry files, and provides some limited support for DICOM. The scope is a domain rather than a feature list. The formats are the ones a neuroimaging lab actually collects, and the value of the package is that a pipeline written against it does not have to care which of them a given site handed over.

Headers on demand, pixels as NumPy arrays

The API shape is worth stating precisely, because it is the contract your code depends on. NiBabel's API gives full or selective access to header information, which is the metadata, and image data is made available via NumPy arrays. Selective access matters more than it sounds. A NIfTI header can be large and slow to parse, and many workflows only need the shape and the affine of a volume, so being able to read the header without loading the voxels is the difference between scanning a dataset and copying it. The documentation site and the API reference are both linked from the README, and the project is a `Development Status :: 5 - Production/Stable` package, with the maintainer listed as Christopher Markiewicz and the author line as the NiBabel developers with a neuroimaging mailing list address.

Three ways to install it

The installation section gives you the choices that match how you intend to work. For the current release from PyPI, the command is:

pip install nibabel

For the latest development version, the README gives:

pip install git+https://github.com/nipy/nibabel

and for work on NiBabel itself, an editable install of a local clone:

git clone https://github.com/nipy/nibabel.git
pip install -e ./nibabel

The README also points to a release archive and a development changelog for previous versions, which is the kind of pointer that saves time when a pipeline has to be pinned to the version that predates a behaviour change. The package is also distributed through conda-forge, and the badge list shows packages in Debian Unstable, Arch, Gentoo and nixpkgs, so the distribution channels for a scientific tool are well covered.

Eleven command line tools come with it

The `pyproject.toml` registers a set of console scripts, and they are the fastest way to see what the library does. There is `nib-convert` to convert between formats and `nib-conform` to bring a file into conformance with a specification, `nib-ls` to list what is inside a file, `nib-diff` to compare two files, `nib-stats` for statistics, and `nib-nifti-dx` for the NIfTI command line extensions. There is a DICOM filesystem tool, `nib-dicomfs`, a ROI extraction tool, `nib-roi`, a tool to convert Philips PAR/REC directories into a NIfTI file, `parrec2nii`, and a pair for tractography streamlines, `nib-tck2trk` and `nib-trk2tck`, which convert between the TCK and TRK formats. The repository topics list both `tck` and `trk` for that reason.

Optional extras decide which formats you actually get

The dependency list in the `pyproject.toml` is short on purpose, with numpy at 2.0 or later, `packaging`, and `importlib_resources` and `typing_extensions` only on older interpreters. Everything heavier sits behind extras. There is an `all` extra that pulls in the others, and the named features include `indexed_gzip` for reading compressed data without decompressing it all, `dicom` and `dicomfs` for the DICOM side, and `minc2`, `spm` and `zstd`. The `indexed_gzip` extra is the one to know about, because reading a large gzipped NIfTI sequentially is a common bottleneck in a batch pipeline, and the extra exists to address exactly that. A second optional dependency, `hdf5`, and the `tables` package are what back the formats that need HDF5 containers.

Testing NiBabel itself, with tox or with pytest

There is a separate section for tests because the project takes its own test coverage seriously. During development, the README recommends tox to run the nibabel tests:

git clone https://github.com/nipy/nibabel.git
cd nibabel
tox

To test an installed version, you install the test dependencies and run pytest against the installed package:

pip install nibabel[test]
pytest --pyargs nibabel

The difference matters for a pipeline that installs from PyPI. Running `pytest --pyargs nibabel` exercises the code that is actually installed rather than a source checkout, which catches packaging problems that a source-tree test run would miss. The repository also carries a `tox.ini`, a `.coveragerc`, a `codecov.yml` and a `Makefile` with separate `Makefile.win`, and the CI badge points at a stable tests workflow, so the released version is tested on every change.

MIT with a BSD tail, and a DOI for the releases

The licensing is straightforward with one footnote. NiBabel is licensed under the terms of the MIT license, and some code included with NiBabel is licensed under the BSD license, with the details in the COPYING file, which is where a redistributor should look rather than assuming a single grant. The repository classification says the licence is a custom one that the platform cannot map to a standard identifier, which is a consequence of that mixture rather than a restriction. For citation, the README says NiBabel releases carry a Zenodo Digital Object Identifier badge at the top of the release notes, and the badge points at a specific DOI, so a paper that used a given release can point at that exact artefact. The packaging is modern, with hatchling and hatch-vcs building the package and deriving the version from the tags, and the development versions around the 5.4 and 5.3 lines in late 2025 and early 2026 sit against a long history of 0.x releases.

Editorial conclusion

Adopt NiBabel when your Python pipeline has to read or write neuroimaging volumes, surfaces, tractographies or DICOM data in more than one vendor format, since the format coverage and the stable API are the reason it exists. Do not adopt it for general image processing, since it is scoped to neuro-imaging formats and hands you NumPy arrays rather than an imaging pipeline. Verify first which optional extras you need, since DICOM, indexed gzip, MINC, SPM and zstd support are separate extras rather than always installed, and note that the package now requires Python 3.11 and NumPy 2.

Frequently asked questions

Official sources

1. Issues
2. nipy/nibabel on GitHub
3. Project website
4. README
5. Releases