{"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":"python","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,"search_vec":"'-2':35 '5.4.2':64 'access':13,53 'activ':5 'afni':31 'analyz':24 'array':17,51 'brain':87 'brik/head':32 'bug':74 'bug-fix':73 'cadenc':70 'cifti':34 'consist':68 'current':61 'data':48 'dicom':40,83 'ecat':28 'enabl':42 'featur':77 'file':20 'fix':75 'format':21,55 'format-specif':54 'frequent':72 'gifti':25 'header':60 'imag':47,81,84,88 'includ':22 'interact':45 'limit':37 'maintain':66 'medic':80 'metadata':57 'mgh':27 'minc':26 'neuroimag':19,79 'nibabel':1,2,65 'nifti':23,82 'numpi':50,86 'packag':7 'par/rec':30 'philip':29 'process':85 'provid':9 'python':6 'read':10 'releas':69 'specif':56 'structur':59 'support':38 'updat':78 'user':43 'version':63 'wide':16 'write':12","created_at":"2026-04-11T17:41:32.277680+00:00","updated_at":"2026-04-17T15:04:23.946073+00:00","problems":[{"fix":"Use `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.","cause":"The `get_data()` method was deprecated and removed in recent `nibabel` versions; image data is now accessed via `get_fdata()` or the `dataobj` attribute.","error":"AttributeError: module 'nibabel' has no attribute 'get_data'"},{"fix":"Verify 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.","cause":"The specified file path does not exist, is misspelled, or is not accessible from the current working directory.","error":"FileNotFoundError: [Errno 2] No such file or directory: '/path/to/your/image.nii.gz'"},{"fix":"Reshape 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.","cause":"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.","error":"ValueError: Data passed is not 3D, and cannot be saved as NIfTI-1."},{"fix":"Ensure 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.","cause":"The specified file is either corrupted, not a valid neuroimaging file format that `nibabel` can parse, or its header is unreadable.","error":"nibabel.spatialimages.ImageFileError: Error reading header for file /path/to/image.nii.gz"},{"fix":"pip install nibabel","cause":"The nibabel package is not installed in your Python environment.","error":"ModuleNotFoundError: No module named 'nibabel'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"5.4.2","cli_name":"nib-dicomfs","cli_version":"nib-dicomfs 5.4.2","type":"library","homepage":"https://nipy.org/nibabel","github":"https://github.com/nipy/nibabel","docs":null,"changelog":null,"pypi":"https://pypi.org/project/nibabel/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["data","serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-29","next_check":"2026-07-28","install_tag":null}}