Overview
NiBabel is the core Python library for neuroimaging file I/O. Use it to read and write NIfTI, GIFTI, CIFTI, MGH, MINC, and Analyze files, inspect affine metadata, and move data between imaging tools and NumPy.
Installation
uv pip install nibabel
Load a NIfTI volume
import nibabel as nib
img = nib.load('brain_t1.nii.gz')
data = img.get_fdata()
affine = img.affine
header = img.header
print(data.shape)
print(header.get_zooms())
print(affine)
Save a modified image
import numpy as np
masked = (data > data.mean()).astype(np.float32)
out = nib.Nifti1Image(masked, affine, header)
nib.save(out, 'brain_mask.nii.gz')
4D fMRI example
fmri = nib.load('rest_bold.nii.gz')
arr = fmri.get_fdata() # shape like (x, y, z, t)
tr = fmri.header.get_zooms()[-1]
print(arr.shape, tr)
Coordinate handling
NiBabel stores the affine transform from voxel coordinates to world coordinates. Do not ignore it if you are mixing tools, resampling data, or comparing scans across sessions.
Workflow
- Load with
nib.load().
- Inspect shape, affine, voxel spacing, and orientation assumptions.
- Use
.get_fdata() when you want floating-point arrays.
- When saving derived outputs, preserve affine/header unless intentionally changing them.
- For resampling/reorientation, combine with Nilearn, DIPY, or ANTs/SimpleITK workflows rather than hacking the array blindly.
1---2name: nibabel3description: Read and write neuroimaging file formats: NIfTI, GIFTI, CIFTI, MGH, Minc, Analyze, SPM. Core I/O for fMRI, diffusion MRI, structural MRI pipelines. Use when handling brain imaging data.4---5## Overview67NiBabel is the core Python library for neuroimaging file I/O. Use it to read and write NIfTI, GIFTI, CIFTI, MGH, MINC, and Analyze files, inspect affine metadata, and move data between imaging tools and NumPy.89## Installation1011```bash12uv pip install nibabel13```1415## Load a NIfTI volume1617```python18import nibabel as nib1920img = nib.load('brain_t1.nii.gz')21data = img.get_fdata()22affine = img.affine23header = img.header2425print(data.shape)26print(header.get_zooms())27print(affine)28```2930## Save a modified image3132```python33import numpy as np3435masked = (data > data.mean()).astype(np.float32)36out = nib.Nifti1Image(masked, affine, header)37nib.save(out, 'brain_mask.nii.gz')38```3940## 4D fMRI example4142```python43fmri = nib.load('rest_bold.nii.gz')44arr = fmri.get_fdata() # shape like (x, y, z, t)45tr = fmri.header.get_zooms()[-1]46print(arr.shape, tr)47```4849## Coordinate handling5051NiBabel stores the affine transform from voxel coordinates to world coordinates. Do not ignore it if you are mixing tools, resampling data, or comparing scans across sessions.5253## Workflow54551. Load with `nib.load()`.562. Inspect shape, affine, voxel spacing, and orientation assumptions.573. Use `.get_fdata()` when you want floating-point arrays.584. When saving derived outputs, preserve affine/header unless intentionally changing them.595. For resampling/reorientation, combine with Nilearn, DIPY, or ANTs/SimpleITK workflows rather than hacking the array blindly.
mkurman