Install & Compatibility
Where this runs
tested against v5.4.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.534s · 102.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.4s · import 0.498s · 99MB
103MB installed
● package 103MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
nibabel
✓ import nibabel as nib
Standard convention for brevity and common use.
Nifti1Image
✓ from nibabel.nifti1 import Nifti1Image
✗ from nibabel import Nifti1Image
Specific image classes are within submodules, not directly under `nibabel` top-level.
This quickstart demonstrates how to create a simple NIfTI image, save it to disk, then load it back into NiBabel. It shows how to access the image's data as a NumPy array and retrieve its affine transformation matrix. Finally, it cleans up the created dummy file.
import nibabel as nib
import numpy as np
import os
# Create a dummy NIfTI image for demonstration
data = np.arange(27, dtype=np.int16).reshape((3, 3, 3))
affine = np.diag([2, 2, 2, 1])
img = nib.Nifti1Image(data, affine)
# Save the dummy image
output_filename = 'dummy_image.nii.gz'
nib.save(img, output_filename)
print(f"Saved dummy image to {output_filename}")
# Load the image
loaded_img = nib.load(output_filename)
# Access image data as a NumPy array
image_data = loaded_img.get_fdata()
print(f"Loaded image shape: {image_data.shape}")
print(f"Loaded image data type: {image_data.dtype}")
# Access the affine transformation matrix
image_affine = loaded_img.affine
print(f"Loaded image affine:\n{image_affine}")
# Clean up the dummy file
os.remove(output_filename)
print(f"Cleaned up {output_filename}")
nib-dicomfs --version
Debug
Known issues
deprecatedThe `get_data()` method for accessing image data is deprecated. It returns a `numpy.ndarray` for in-memory data but an `ArrayProxy` for memory-mapped data, leading to inconsistent behavior.fixUse `img.get_fdata()` instead, which always returns a `numpy.ndarray` and explicitly loads data into memory if necessary. For proxy behavior, use `numpy.asanyarray(img.dataobj)`.
affects: 3.0 and later, will raise `ExpiredDeprecationError` as of version 5.0.
breakingNiBabel 6.0 (expected after 5.x series) will drop support for NumPy 1.x, requiring NumPy 2.0 or later.fixEnsure your environment uses NumPy 2.0 or a compatible future version before upgrading to NiBabel 6.0. Current NiBabel 5.x series support NumPy 1.25+.
affects: Upcoming NiBabel 6.0 and beyond.
gotchaMinimum Python and NumPy version requirements have increased across major/minor releases. For example, NiBabel 5.4.x requires Python 3.10+ and NumPy 1.25+.fixAlways check the `requires_python` and `dependencies` in `pyproject.toml` or the official documentation for the exact version of NiBabel you are installing to ensure environment compatibility. Use `pip install nibabel==X.Y.Z` and review dependencies.
affects: All versions, specifically when upgrading across major/minor boundaries.
deprecatedThe `nibabel.onetime.auto_attr` module is deprecated. Its functionality is now available in the standard library.fixReplace usages of `nibabel.onetime.auto_attr` with `functools.cached_property` where applicable.
affects: All supported versions (can be replaced by `functools.cached_property`). May be removed in future versions.
breakingAttempting to set the qform (quaternion form) that fails decomposition will now raise a more specific `nibabel.spatialimages.HeaderDataError` instead of a generic `numpy.linalg.LinAlgError`.fixUpdate exception handling code to catch `nibabel.spatialimages.HeaderDataError` when calling `set_qform` or related methods that perform affine decomposition.
affects: NiBabel 5.3.0 and later.
Errors
Common errors & fixes
AttributeError: module 'nibabel' has no attribute 'get_data'
The `get_data()` method was deprecated and removed in recent `nibabel` versions; image data is now accessed via `get_fdata()` or the `dataobj` attribute.
fixUse `img.get_fdata()` to get the image data as a floating-point NumPy array, or `img.dataobj` for a proxy object with various data access options.
FileNotFoundError: [Errno 2] No such file or directory: '/path/to/your/image.nii.gz'
The specified file path does not exist, is misspelled, or is not accessible from the current working directory.
fixVerify the file path is correct, including the filename and extension, and ensure the file is present at that location. Use an absolute path or confirm the relative path is correct from where the script is executed.
ValueError: Data passed is not 3D, and cannot be saved as NIfTI-1.
NIfTI-1 format requires image data to have at least three dimensions (e.g., x, y, z), but the NumPy array provided to `nibabel.Nifti1Image` has fewer than three dimensions.
fixReshape the data array to be at least 3-dimensional before creating the `Nifti1Image` object, for example, by adding a singleton dimension for 2D data using `np.expand_dims()` or by slicing.
nibabel.spatialimages.ImageFileError: Error reading header for file /path/to/image.nii.gz
The specified file is either corrupted, not a valid neuroimaging file format that `nibabel` can parse, or its header is unreadable.
fixEnsure the file is not corrupted and is indeed a recognized `nibabel` format (e.g., NIfTI, ANALYZE). Check the file's integrity using an external viewer or a validation tool.
ModuleNotFoundError: No module named 'nibabel'
The nibabel package is not installed in your Python environment.
Upgrade
Version history
5.4.2latest on PyPI · released Mar 11, 2026
Audit
Dependencies
numpyrequiredCore dependency for array manipulation.
packagingrequiredUsed for version parsing and compatibility checks.
importlib-resourcesrequiredBackport for `importlib.resources` functionality on Python < 3.12.
typing_extensionsrequiredProvides backported typing features for Python < 3.13.
scipyoptionalOptional, for full SPM-ANALYZE support and some image processing utilities.
h5pyoptionalOptional, for MINC2 support.
pydicomoptionalOptional, for DICOM support.
pillowoptionalOptional, for PNG conversion in DICOMFS.
indexed_gzipoptionalOptional, for faster access to gzipped files.