dicom2nifti

2.6.2 verified Mon Apr 27 auth: no python

A Python library for converting DICOM series to NIfTI format, with support for enhanced, CT, MR, and PET images. Current version 2.6.2, released 2025. Maintained by icometrix.

pip install dicom2nifti

Common errors

error AttributeError: module 'dicom2nifti' has no attribute 'dicom_to_nifti' ↓

cause The function was renamed or removed in version 2.0.

fix

Use dicom2nifti.dicom_series_to_nifti() instead.

error ValueError: The input is not a valid DICOM series ↓

cause The input directory contains files that are not DICOM, multiple series, or incomplete data.

fix

Ensure the folder contains exactly one DICOM series with correct filenames (e.g., from a single DICOM study).

error ImportError: No module named 'pydicom' ↓

cause Dependency pydicom not installed.

fix

Run pip install pydicom or reinstall dicom2nifti with all dependencies: pip install dicom2nifti.

error KeyError: 'SeriesInstanceUID' ↓

cause Some DICOM files are missing required tags because they are not valid DICOM or corrupted.

fix

Validate your DICOM files with pydicom.dcmread() to check for missing tags.

Warnings

gotcha The function `dicom_series_to_nifti` expects a folder containing exactly one DICOM series. If the folder contains multiple series or non-DICOM files, conversion may fail or produce incorrect output. ↓

fix Ensure input folder contains only one series; use `dicom_series_to_nifti` with `dir` only for single-series directories.

deprecated The function `dicom_array_to_nifti` is deprecated since version 2.0 and may be removed in future releases. Use `dicom_series_to_nifti` with a directory instead. ↓

fix Replace with `dicom_series_to_nifti` using a temporary directory containing the DICOM files.

breaking In version 2.0, support for Python 2 was dropped and the API was simplified. Functions like `dicom_to_nifti` and `dicom_to_nifti_parallel` were removed. ↓

fix Use `dicom_series_to_nifti` for single series or `dicom_series_to_nifti_multi` for multiple series.

gotcha The `reorient_nifti` parameter defaults to `True`. If you need to preserve original orientation, set it to `False` explicitly. ↓

fix Call with `reorient_nifti=False` if you do not want reorientation.

gotcha Conversion may lose private tags or metadata. The library only supports standard DICOM tags and may not preserve all attributes. ↓

fix Use `pydicom` directly to extract any needed private tags before conversion.

Imports

dicom2nifti
wrong
```
from dicom2nifti import dicom2nifti
```
correct
```
import dicom2nifti
```
The module itself is the function; do not import submodule.

Quickstart

Convert a directory of DICOM files (single series) to NIfTI.

import dicom2nifti

dicom2nifti.dicom_series_to_nifti('/input/dicom/folder', '/output.nii.gz', reorient_nifti=True)