{"id":3713,"library":"nibabel","title":"NiBabel","description":"NiBabel is an active Python package that provides read and write access to a wide array of neuroimaging file formats, including NIfTI, ANALYZE, GIFTI, MINC, MGH, ECAT, Philips PAR/REC, AFNI BRIK/HEAD, and CIFTI-2, with limited support for DICOM. It enables users to interact with image data as NumPy arrays and access format-specific metadata through structured headers. Currently at version 5.4.2, NiBabel maintains a consistent release cadence with frequent bug-fix and feature updates.","status":"active","version":"5.4.2","language":"en","source_language":"en","source_url":"https://github.com/nipy/nibabel","tags":["neuroimaging","medical imaging","NIfTI","DICOM","image processing","numpy","brain imaging"],"install":[{"cmd":"pip install nibabel","lang":"bash","label":"Install latest stable release"}],"dependencies":[{"reason":"Core dependency for array manipulation.","package":"numpy","optional":false},{"reason":"Used for version parsing and compatibility checks.","package":"packaging","optional":false},{"reason":"Backport for `importlib.resources` functionality on Python < 3.12.","package":"importlib-resources","optional":false},{"reason":"Provides backported typing features for Python < 3.13.","package":"typing_extensions","optional":false},{"reason":"Optional, for full SPM-ANALYZE support and some image processing utilities.","package":"scipy","optional":true},{"reason":"Optional, for MINC2 support.","package":"h5py","optional":true},{"reason":"Optional, for DICOM support.","package":"pydicom","optional":true},{"reason":"Optional, for PNG conversion in DICOMFS.","package":"pillow","optional":true},{"reason":"Optional, for faster access to gzipped files.","package":"indexed_gzip","optional":true}],"imports":[{"note":"Standard convention for brevity and common use.","symbol":"nibabel","correct":"import nibabel as nib"},{"note":"Specific image classes are within submodules, not directly under `nibabel` top-level.","wrong":"from nibabel import Nifti1Image","symbol":"Nifti1Image","correct":"from nibabel.nifti1 import Nifti1Image"}],"quickstart":{"code":"import nibabel as nib\nimport numpy as np\nimport os\n\n# Create a dummy NIfTI image for demonstration\ndata = np.arange(27, dtype=np.int16).reshape((3, 3, 3))\naffine = np.diag([2, 2, 2, 1])\nimg = nib.Nifti1Image(data, affine)\n\n# Save the dummy image\noutput_filename = 'dummy_image.nii.gz'\nnib.save(img, output_filename)\nprint(f\"Saved dummy image to {output_filename}\")\n\n# Load the image\nloaded_img = nib.load(output_filename)\n\n# Access image data as a NumPy array\nimage_data = loaded_img.get_fdata()\nprint(f\"Loaded image shape: {image_data.shape}\")\nprint(f\"Loaded image data type: {image_data.dtype}\")\n\n# Access the affine transformation matrix\nimage_affine = loaded_img.affine\nprint(f\"Loaded image affine:\\n{image_affine}\")\n\n# Clean up the dummy file\nos.remove(output_filename)\nprint(f\"Cleaned up {output_filename}\")","lang":"python","description":"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."},"warnings":[{"fix":"Use `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)`.","message":"The `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.","severity":"deprecated","affected_versions":"3.0 and later, will raise `ExpiredDeprecationError` as of version 5.0."},{"fix":"Ensure 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+.","message":"NiBabel 6.0 (expected after 5.x series) will drop support for NumPy 1.x, requiring NumPy 2.0 or later.","severity":"breaking","affected_versions":"Upcoming NiBabel 6.0 and beyond."},{"fix":"Always 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.","message":"Minimum 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+.","severity":"gotcha","affected_versions":"All versions, specifically when upgrading across major/minor boundaries."},{"fix":"Replace usages of `nibabel.onetime.auto_attr` with `functools.cached_property` where applicable.","message":"The `nibabel.onetime.auto_attr` module is deprecated. Its functionality is now available in the standard library.","severity":"deprecated","affected_versions":"All supported versions (can be replaced by `functools.cached_property`). May be removed in future versions."},{"fix":"Update exception handling code to catch `nibabel.spatialimages.HeaderDataError` when calling `set_qform` or related methods that perform affine decomposition.","message":"Attempting 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`.","severity":"breaking","affected_versions":"NiBabel 5.3.0 and later."}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}