dcm2niix: DICOM to NIfTI Conversion Guide

dcm2niix is an open-source software utility designed to convert raw medical imaging data from the Digital Imaging and Communications in Medicine (DICOM) standard into the Neuroimaging Informatics Technology Initiative (NIfTI) format. In modern neuroscience research, scanner acquisitions cannot be analyzed directly by statistical software; dcm2niix bridges this gap by reorganizing disparate slice files into contiguous 3D or 4D volumes while preserving spatial geometries and acquisition physics.

What it is used for in research

In cognitive neuroscience, neurobiology, and clinical imaging trials, magnetic resonance imaging (MRI), computed tomography (CT), and positron emission tomography (PET) scanners store acquisitions as collections of two-dimensional DICOM files. Analyzing these slices requires converting them to NIfTI (.nii or compressed .nii.gz), which represents 3D brain volumes and 4D time series along explicit affine coordinate frames (sform and qform matrices). dcm2niix resolves vendor-specific variations in slice ordering, gantry tilt, and coordinate conventions across manufacturers including Siemens, GE Healthcare, Philips, Canon, and United Imaging.

Beyond basic matrix translation, researchers rely on dcm2niix for data curation within the Brain Imaging Data Structure (BIDS). During conversion, dcm2niix extracts acquisition parameters into companion BIDS JSON sidecars, capturing repetition times (TR), echo times (TE), flip angles, phase-encoding directions, and slice-timing arrays. For diffusion-weighted imaging (DWI), it extracts gradient tables into paired .bval and .bvec text files, adjusting vector orientations for scanner-specific frame rotations. Standardizing datasets through this pipeline enables streamlined ingestion into repositories such as OpenNeuro BIDS neuroimaging data sharing archives.

Install or access

dcm2niix is distributed as a standalone executable for macOS, Linux, and Windows, requiring no external runtime dependencies for standard conversion. Validated installation routes include:

Precompiled Releases: Download official release archives directly from GitHub (rordenlab/dcm2niix) or via curl:

curl -fLO https://github.com/rordenlab/dcm2niix/releases/latest/download/dcm2niix_lnx.zip
unzip dcm2niix_lnx.zip

Package Managers:
- macOS (Homebrew): brew install dcm2niix
- Linux (Debian/Ubuntu): sudo apt-get install dcm2niix
- Python environments: pip install dcm2niix or conda install -c conda-forge dcm2niix
Bundled Distributions: The tool is bundled within graphical neuroimaging applications, including MRIcroGL (under Import > Convert DICOM to NIfTI) and neuroimaging environments like NeuroDebian and FreeSurfer.

Source Compilation (CMake): For custom architectures or accelerated compression:

git clone https://github.com/rordenlab/dcm2niix.git
cd dcm2niix && mkdir build && cd build
cmake -DZLIB_IMPLEMENTATION=zlib-ng -DUSE_JPEGLS=ON ..
make && sudo make install

Step-by-step task

Converting a directory of raw DICOM acquisitions into compressed NIfTI files with BIDS sidecars follows a standardized command-line sequence:

Organize Raw Data: Place uncompressed scanner DICOM files into a dedicated source directory (e.g., /data/raw_dicoms/sub-01/). Ensure all slice files belonging to an acquisition series remain grouped together.
Inspect Command Options: Check version and syntax flags by running dcm2niix -h. Primary parameters include -o (output folder), -z (compression mode), -f (filename format), and -b (BIDS sidecar generation).
Execute Basic Gzip Conversion: Convert an entire subject session to compressed NIfTI:
```
dcm2niix -z y -o /data/nifti/sub-01 /data/raw_dicoms/sub-01
```
Here, -z y invokes internal gzip compression or leverages parallel pigz if present on the system path.
Apply Structured Filename Formatting: Use format specifiers to name output files according to acquisition metadata:
```
dcm2niix -z y -f %p_%s_%t -o /data/nifti/sub-01 /data/raw_dicoms/sub-01
```
In this command, %p inserts the protocol name, %s inserts the series number, and %t inserts the scan acquisition time.
Automate ReproIn BIDS Naming: For scanner protocols configured with ReproIn naming rules, execute one-pass BIDS conversion with de-identification:
```
dcm2niix -f %H -ba y -o /data/bids_dataset /data/raw_dicoms/sub-01
```
The flag -f %H generates BIDS-structured hierarchies, while -ba y anonymizes the resulting JSON sidecar by stripping patient identifying information and direct timestamps.
Verify Output Integrity: Confirm that 3D structural volumes, 4D functional series, and companion .json sidecars were generated without dropped slices. When documenting methods in publications, link formal protocol references using a persistent Crossref DOI.

Output and how to read it

A typical dcm2niix execution generates several interdependent file types depending on the imaging modality:

Volumetric NIfTI Images (.nii / .nii.gz): Stores voxel intensities and a 348-byte header detailing matrix dimensions, voxel dimensions (in millimeters), and rigid-body affine transformation matrices (sform and qform) that map voxel indices to scanner anatomical coordinates.
BIDS JSON Sidecars (.json): Human-readable text files containing acquisition physics. Key attributes include:
- RepetitionTime and EchoTime: Essential timing parameters required for hemodynamic modeling.
- PhaseEncodingDirection: Vector orientation code (e.g., j-) required by geometric distortion-correction tools.
- SliceTiming: Array of slice acquisition delays relative to the volume TR, required for slice-timing correction.
- Manufacturer and MagneticFieldStrength: Hardware metadata verifying sequence consistency across study sites.
Diffusion Gradient Files (.bval and .bvec): Generated exclusively for diffusion MRI series:
- .bval: A single row of space-separated integers specifying the diffusion weighting (b-values in s/mm²).
- .bvec: Three rows of floating-point numbers representing unit gradient direction vectors (X, Y, Z), rotated into image matrix space.

Troubleshooting

Conversion errors typically stem from incomplete file transfers, vendor-specific private headers, or mismatched coordinate frames:

Missing Slices or Unequal Slice Intervals: NIfTI requires equidistant slices. If a scan was aborted mid-run or localizer slices with varying thicknesses were saved in the same series, dcm2niix issues a warning and splits the series into sub-volumes (e.g., appending _Eq_1). Verify scanner completeness before reprocessing.
Inverted Diffusion Vectors: Discrepancies between scanner reference frames and processing pipelines can result in tractography artifacts. dcm2niix rotates b-vectors to match NIfTI space; verify orientations with MRtrix dwigradcheck before tractography. This precision is vital when contrasting structural models in neuroscience vs neurobiology research.
Derived or Secondary Images: Scanners frequently compute mean ADC maps or reconstructed MIPs. dcm2niix labels these derived series (e.g., appending _ADC). Exclude derived series from primary preprocessing pipelines to prevent double-processing.
Compressed DICOM Codecs: If source DICOMs utilize JPEG-LS or JPEG2000 compression and dcm2niix was compiled without CharLS or OpenJPEG, conversion will abort. Download the official precompiled binaries bundled with MRIcroGL to resolve codec dependencies.

Free alternatives

While dcm2niix is the reference conversion engine for automated pipelines, several established alternatives serve specialized environments:

Tool	Environment	Primary Focus	BIDS Sidecar Support	Key Advantage
dcm2niix	C/C++ standalone CLI	Universal DICOM to NIfTI/BIDS conversion	Native automated JSON export	Fast, lightweight, zero dependencies, bundled parallel pigz compression.
dicm2nii	MATLAB	Research MRI conversion	Yes (MATLAB structure/JSON)	Highly scriptable within existing MATLAB and SPM preprocessing scripts.
dicom2nifti	Python	Python-native pipelines	Partial	Direct integration with Python workflows using high-performance GDCM binaries.
FreeSurfer mri_convert	C / Linux / macOS	FreeSurfer surface reconstruction	No (NIfTI header only)	Native translation between DICOM, MGH, MGZ, and NIfTI within FreeSurfer recon-all.
SPM12 DICOM Import	MATLAB	Statistical Parametric Mapping	No (MATLAB headers)	Direct conversion into SPM-compatible 3D and 4D volumetric NIfTI files.
Plastimatch	C++ CLI / Library	Radiation oncology and medical imaging	No	Specialized handling of DICOM RT structures, dose grids, and CT volumes.

FAQ

Why does dcm2niix create a JSON file next to the NIfTI file?

The companion JSON file contains acquisition metadata extracted from DICOM headers that cannot fit inside the fixed 348-byte NIfTI header. This includes repetition time, echo time, phase-encoding direction, and slice-timing information, formatted according to Brain Imaging Data Structure (BIDS) specifications.

How do I convert a folder of DICOM files without gzip compression?

To produce uncompressed NIfTI (.nii) files instead of compressed (.nii.gz) files, pass the flag -z n or -z o in your command: dcm2niix -z n -o /output /dicom_folder.

Does dcm2niix anonymize patient information?

Yes. By default, dcm2niix strips direct patient identifiers (such as patient name and patient ID) from the generated NIfTI header. When using the anonymization flag -ba y, personal health information (PHI) and acquisition dates are also redacted from the companion BIDS JSON sidecar.

What are the .bval and .bvec files created during diffusion conversion?

These text files describe the diffusion gradients used in diffusion tensor imaging (DTI). The .bval file lists the b-value (diffusion weighting strength) for each volume, and the .bvec file lists the directional vectors (X, Y, Z), rotated to match the image matrix orientation.

Sources

Li, X., Morgan, P. S., Ashburner, J., Smith, J., & Rorden, C. (2016). The first step for neuroimaging data analysis: DICOM to NIfTI conversion. Journal of Neuroscience Methods, 264, 47-56. https://doi.org/10.1016/j.jneumeth.2016.03.001 (Read 2026-11-08)
Rorden Lab. (2026). dcm2niix Official Repository and Documentation. https://github.com/rordenlab/dcm2niix (Read 2026-11-08)
Neuroimaging Informatics Tools and Resources Clearinghouse (NITRC). (2026). dcm2nii and dcm2niix Documentation Manual. http://www.nitrc.org/plugins/mwiki/index.php/dcm2nii:MainPage (Read 2026-11-08)