dcm2niix

dcm2niix

About

dcm2niix is designed to convert neuroimaging data from the DICOM format to the NIfTI format. This web page hosts the developmental source code - a compiled version for Linux, MacOS, and Windows of the most recent stable release is included with MRIcroGL. A full manual for this software is available in the form of a NITRC wiki.

The DICOM format is the standard image format generated by modern medical imaging devices. However, DICOM is very complicated and has been interpreted differently by different vendors. The NIfTI format is popular with scientists, it is very simple and explicit. However, this simplicity also imposes limitations (e.g. it demands equidistant slices). dcm2niix is also able to generate a BIDS JSON format sidecar which includes relevant information for brain scientists in a vendor agnostic and human readable form. The Neuroimaging DICOM and NIfTI Primer provides details.

JavaScript/WebAssembly

To view the WASM specific README, please click here. The rest of this README is for the dcm2niix CLI program.

License

This software is open source. The bulk of the code is covered by the BSD license. Some units are either public domain (nifti*.*, miniz.c) or use the MIT license (ujpeg.cpp). See the license.txt file for more details.

Dependencies

This software should run on macOS, Linux and Windows typically without requiring any other software. However, if you use dcm2niix to create gz-compressed images it will be faster if you have pigz installed. You can get a version of both dcm2niix and pigz compiled for your operating system by downloading MRIcroGL.

Image Conversion and Compression

DICOM provides many ways to store/compress image data, known as transfer syntaxes. The COMPILE.md file describes details on how to enable different options to provide support for more formats.

• The base code includes support for raw, run-length encoded, and classic JPEG lossless decoding.
• Lossy JPEG is handled by the included NanoJPEG. This support is modular: you can compile for libjpeg-turbo or disable it altogether.
• JPEG-LS lossless support is optional, and can be provided by using CharLS.
• JPEG2000 lossy and lossless support is optional, and can be provided using OpenJPEG or Jasper.
• GZ compression (e.g. creating .nii.gz images) is optional, and can be provided using either the included miniz or the popular zlib. Of particular note, the Cloudflare zlib exploits modern hardware (available since 2008) for very rapid compression. Alternatively, you can compile dcm2niix without a gzip compressor. Regardless of how you compile dcm2niix, it can use the external program pigz for parallel compression.
• Zstandard compression (creating .nii.zst images via -z s) is optional, and can be enabled with -DUSE_ZSTD=ON (CMake) or ZSTD=1 make (Makefile). Zstandard offers a favorable compression/speed tradeoff compared to gzip.
• Siemens physio recordings stored as DICOM (XA30/XA60 PhysioLogging Raw Data Storage SOPs carrying a gzipped XML payload, and legacy CMRR Multi-Band VE11C PMU DICOMs carrying a raw binary blob in the Siemens CSA Non-Image Storage SOP) are extracted to BIDS-compliant _recording-<label>_physio.tsv.gz files with companion .json sidecars (cardiac/respiratory/ecg/external_trigger streams), rather than skipped as non-image. For CMRR streams that carry firmware-detected R-wave / respiratory peaks, the TSV is 3 columns — [<signal>, trigger, <signal>_trigger] — where column 2 is BIDS-canonical scanner volume triggers (byte-compatible with bidsphysio) and column 3 carries the per-stream physiological events. The EXT stream is the one exception: its peak column is named external_trigger_peak rather than external_trigger_trigger. When the CMRR Phoenix protocol or physio payload carries a canonical measurement UUID, both the imaging and physio sidecars emit CMRRMeasurementUUID so a physio recording can be paired with its image series; because it links back to the source DICOMs the key is emitted only under -ba n; for CMRR sequences the same UUID also leads WipMemBlock, which -ba y redacts and -ba o retains alongside the DICOM UIDs it deliberately keeps. The sibling regression set dcm_qa_physio documents the column layout, the VALUE=2048 trigger-sentinel encoding, and the deliberate divergence from bidsphysio (which remains the canonical post-processor for richer cases).
• MR spectroscopy (Siemens VB/VE/XA SVS + single-DICOM Enhanced CSI, Philips classic + Enhanced SVS, UIH SVS + single-DICOM 2D/3D MRSI) is converted to BIDS-MRS compliant complex-float NIfTI + .json sidecars (including _mrsi suffix and a 4×4 VOI matrix emitted when sufficient source VOI metadata is present). Multi-DICOM classic Siemens CSI/MRSI is not supported. Non-square UIH MRSI grids produce correct dim/payload alignment matching spec2nii (dcm2niix deliberately mirrors spec2nii’s transposed affine/data-shape coupling for byte parity). Philips classic 2× payloads emit a paired <stem>_mrsref.nii.gz water-reference companion; standalone water-reference acquisitions (wrsoff / no_Water_Suppression series-naming) are relabeled _mrsref with WaterSuppressed: false. Vendor-sequence-state-specific reshapes / splits (CMRR sLASER DKD reference-scan ordering, Philips MEGA-PRESS edit ON/OFF interpretation) are intentionally NOT done in C — dcm2niix ships raw bundled NIfTIs. The sibling Python tool tools/mrs_post.py (pydicom + numpy) consumes those outputs to produce spec2nii-equivalent split / reshaped files when desired. Ported from spec2nii (BSD-3-Clause, William Clarke, U. Oxford). MRS regression / validation corpus lives in the sibling dcm_qa_mrs repo — current parity: 23/40 PASS bare, 30/40 PASS via --with-mrs-post, 10 SKIP bounded by spec2nii reference availability.

ReproIn one-pass naming (-f %H)

dcm2niix can emit ReproIn/heudiconv-style BIDS filenames in a single pass via the -f %H format specifier, with the optional -bi (subject), -bv (session), and -br (project subdirectory) flags. A companion script tools/reproinx.py handles cross-series concerns (fmap pairing, _scans.tsv, B0FieldIdentifier/B0FieldSource, session backfill, root scaffolding, plus cross-series reclassification such as short reverse-PE EPIs to fmap/_epi and rescue of session-first/suffix-last protocols that the one-pass parser cannot name) and accepts --anonymize, --strict, --keep-derivatives, --no-convert, --min-volumes/-N, and --shift-dates (BIDS-recommended date de-identification: per-subject shift to 1925 preserving relative timing) flags. The anonymisation flag -ba has three modes: y (default; strip dates and patient PII), n (keep both), o (omit patient PII only — keep acquisition timestamps so reproinx’s _scans.tsv and fmap closest-time pairing still work). See REPROIN.md for the full grammar, defaults, privacy considerations, and known limitations.

Versions

See releases for recent release notes. See the VERSIONS.md file for details on earlier releases.

Contribute

dcm2niix is developed by the community for the community and everybody can become a part of the community. Pull requests should target the development branch — master is reserved for tagged stable releases.

Running

Command line usage is described in the NITRC wiki. The minimal command line call would be dcm2niix /path/to/dicom/folder. However, you may want to invoke additional options, for example the call dcm2niix -z y -f %p_%t_%s -o /path/output /path/to/dicom/folder will save data as gzip compressed, with the filename based on the protocol name (%p) acquisition time (%t) and DICOM series number (%s), with all files saved to the folder “output”. For more help see help: dcm2niix -h.

See the BATCH.md file for instructions on using the batch processing version.

dcm2niix can also rename DICOMs instead of converting them (-r y): see RENAMING.md. ERRORS.md lists the exit codes and FILENAMING.md lists the -f format specifiers.

Install

There are a couple ways to install dcm2niix

• Github Releases provides the latest compiled executables. This is an excellent option for MacOS and Windows users. However, the provided Linux executable requires a recent version of Linux (e.g. Ubuntu 14.04 or later), so the provided Unix executable is not suitable for very old distributions. Specifically, it requires Glibc 2.19 (from 2014) or later. Users of older systems can compile their own copy of dcm2niix or download the compiled version included with MRIcroGL Glibc 2.12 (from 2011, see below).
• Run the following command to get the latest release version for Linux, Macintosh or Windows:
  • curl -fLO https://github.com/rordenlab/dcm2niix/releases/latest/download/dcm2niix_lnx.zip
  • curl -fLO https://github.com/rordenlab/dcm2niix/releases/latest/download/macos_dcm2niix.pkg
  • curl -fLO https://github.com/rordenlab/dcm2niix/releases/latest/download/dcm2niix_win.zip
• Latest development builds are available as artifacts from GitHub Actions for Linux, Macintosh, and Windows.
• MRIcroGL (NITRC) or MRIcroGL (GitHub) includes dcm2niix that can be run from the command line or from the graphical user interface (select the Import menu item). The Linux version of dcm2niix is compiled on a holy build box, so it should run on any Linux distribution.
• If you have a MacOS computer with Homebrew or MacPorts you can run brew install dcm2niix or sudo port install dcm2niix, respectively.
• If you have Conda, conda install -c conda-forge dcm2niix on Linux, MacOS or Windows.
• If you have pip, python -m pip install dcm2niix on Linux, MacOS or Windows.
• On Debian Linux computers you can run sudo apt-get install dcm2niix.

Build from source

It is often easier to download and install a precompiled version. However, you can also build from source.

Build command line version with cmake (Linux, MacOS, Windows)

cmake and pkg-config (optional) can be installed as follows:

Ubuntu: sudo apt-get install cmake pkg-config

MacOS: brew install cmake pkg-config or sudo port install cmake pkgconfig

Once these tools are available, you can compile with cmake:

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

dcm2niix will be created in the bin subfolder. To install on the system run make install instead of make - this will copy the executable to your path so you do not have to provide the full path to the executable.

In rare case if cmake fails with the message like "Generator: execution of make failed", it could be fixed by sudo ln -s `which make` /usr/bin/gmake.

Building the command line version without cmake

This is the simplest way to compile dcm2niix on a Linux or MacOS computer. Be warned that this minimal version will not be able to extract DICOM images compressed with the (rarely used) JPEG2000 or JPEG-LS formats.

git clone https://github.com/rordenlab/dcm2niix.git
cd dcm2niix/console
make
./dcm2niix

Referencing

• Li X, Morgan PS, Ashburner J, Smith J, Rorden C (2016) The first step for neuroimaging data analysis: DICOM to NIfTI conversion. J Neurosci Methods. 264:47-56. doi: 10.1016/j.jneumeth.2016.03.001. PMID: 26945974

Alternatives

• BIDS-converter hosts Matlab and Python scripts for PET images, supporting DICOM and ECAT (ecat2nii) formats.
• dcm2nii is the predecessor of dcm2niix. It is deprecated for modern images, but does handle image formats that predate DICOM (proprietary Elscint, GE and Siemens formats).
• Python dcmstack DICOM to Nifti conversion with meta data preservation.
• dicm2nii is written in Matlab. The Matlab language makes this very scriptable.
• dicom2nifti uses the scriptable Python wrapper utilizes the high performance GDCMCONV executables.
• dicomtonifti leverages VTK.
• dimon and to3d are included with AFNI.
• dinifti is focused on conversion of classic Siemens DICOMs.
• DWIConvert converts DICOM images to NRRD and NIfTI formats.
• mcverter a great tool for classic DICOMs.
• mrd2nii converts ISMRMRD data into NIfTI images.
• mri_convert is part of the popular FreeSurfer package.
• MRtrix mrconvert is a useful general purpose image converter and handles DTI data well. It is an outstanding tool for modern Philips enhanced images.
• nanconvert uses the ITK library to convert DICOM from GE and proprietary Bruker to standard formats like DICOM.
• Plastimatch is a Swiss Army knife - it computes registration, image processing, statistics and it has a basic image format converter that can convert some DICOM images to NIfTI or NRRD.
• Simple Dicom Reader 2 (Sdr2) uses dcmtk to read DICOM images and convert them to the NIfTI format.
• SlicerHeart extension is specifically designed to help 3D Slicer support ultra sound (US) images stored as DICOM.
• spec2nii converts MR spectroscopy to NIFTI.
• SPM12 is one of the most popular tools in the field. It includes DICOM to NIfTI conversion. Being based on Matlab it is easy to script.

Links

dcm2niix is a core dependency of BIDS converters:

• Table of DICOM to BIDS converters

The following tools exploit dcm2niix

• @niivue/dcm2niix is a WebAssembly (WASM) package of dcm2niix, allowing it to be embedded into web pages, as seen in this live demo.
• abcd-dicom2bids selectively downloads high quality ABCD datasets.
• AFNI bundles dcm2niix_afni.
• autobids automates dcm2bids which uses dcm2niix.
• autobidsify helps convert raw neuroimaging datasets into BIDS-compatible structures.
• BiDirect_BIDS_Converter for conversion from DICOM to the BIDS standard.
• BIDS Toolbox is a web service for the creation and manipulation of BIDS datasets, using dcm2niix for importing DICOM data.
• BIDScoin is a DICOM to BIDS converter with a GUI and thorough documentation.
• bidsconvertr uses R to converts DICOM data to NIfTI and finally to BIDS.
• bidsify is a Python project that uses dcm2niix to convert DICOM and Philips PAR/REC images to the BIDS standard.
• bidskit uses dcm2niix to create BIDS datasets.
• BIDS-Manager GUI and CLI tool for BIDS conversion, curation, metadata editing.
• BIDS_Manager organizes data in BIDS standard.
• bidsme flexible bidsificator for multimodal datasets.
• BIDSvue graphical BIDS anonymization, validation and curation.
• BioImage Suite Web Project is a JavaScript project that uses dcm2niix for its DICOM conversion module.
• birc-bids provides a Docker/Singularity container with various BIDS conversion utilities.
• BMAT translates data from MRI scanners to the BIDS structure.
• BOLD5000_autoencoder uses dcm2niix to pipe imaging data into an unsupervised machine learning algorithm.
• boutiques-dcm2niix is a dockerfile for installing and validating dcm2niix.
• Brain imAgiNg Analysis iN Arcana (Banana) is a collection of brain imaging analysis workflows, it uses dcm2niix for format conversions.
• Brain Lesion Suite supports dcm2niix for DICOM to NifTI conversion.
• brainnetome DiffusionKit uses dcm2niix to convert images.
• BraTS-Preprocessor uses dcm2niix to import files for Brain Tumor Segmentation.
• browserqc web-based quality metrics for DICOM and NIfTI brain scans inspired by mriqc.
• CALMaR Co-designed Automated Lesion Mapping and Reporting.
• CardioNIfTI processes cardiac MR DICOM datasets and converts them to NIfTI.
• clinica is a software platform for clinical neuroimaging studies that uses dcm2niix to convert DICOM images.
• clpipe uses dcm2bids for DICOM import.
• conversion is a Python library that can convert dcm2niix created NIfTI files to the popular NRRD format (including DWI gradient tables). Note, recent versions of dcm2niix can directly convert DICOM images to NRRD.
• convert_source to convert DICOM to BIDS directory layout.
• CT-preprocess brain extract head CT scans.
• d2b-dcm2niix data to BIDS wrapper.
• DAC2BIDS uses dcm2niibatch to create BIDS datasets.
• Data2Bids converts non-DICOM images with associated JSON files to BIDS. While this tool does not require dcm2niix, it can leverage dcm2niix output similar to niix2bids.
• Dcm2Bids uses dcm2niix to create BIDS datasets. Here is a tutorial describing usage.
• dcm2niir R wrapper for dcm2niix/dcm2nii.
• dcm2niix_afni is a version of dcm2niix included with the AFNI distribution.
• dcm2niiXL is a shell script and tuned compilation of dcm2niix designed for accelerated conversion of extra large datasets.
• dcm2niixpy Python package of dcm2niix.
• dcmwrangle a Python interactive and static tool for organizing dicoms.
• deface browser-based anonymization of MR scans.
• DeepDicomSort can recognize different scan types.
• DICOM-to-NIfTI-GUI is a Python script that provides a graphical wrapper for dcm2niix.
• dicom2bids includes python modules for converting dicom files to nifti in a bids-compatible file structure that use dcm2niix.
• DICOM2BIDS is a Python 2 script for creating BIDS files.
• dicom2nifti_batch is a Matlab script for automating dcm2niix.
• dicomConversionToNifti converts, de-identifies and assigns standardized naming convention to medical imaging.
• dicompare-web for automated validation and comparison of MRI acquisition protocols using DICOM metadata.
• divest R interface to dcm2niix.
• DPABI Data Processing & Analysis for Brain Imaging includes dcm2niix.
• dwi2trx web app for processing diffusion data and generating custom gradient tables.
• edgereg DICOM and NIfTI brain registration in the browser.
• Easy-MP2RAGE-T1-Map Quantitative T1 maps from MP2RAGE for desktop or web
• ExploreASL uses dcm2niix to import images.
• ExploreASL-GUI uses dcm2niix for image conversion.
• ezBIDS is a web service for converting directory full of DICOM images into BIDS without users having to learn python nor custom configuration file.
• fmrif tools uses dcm2niix for its oxy2bids tool.
• fMRIprep.dcm2niix is designed to convert DICOM format to the NIfTI format.
• FreeSurfer includes dcm2niix for image conversion.
• fsleyes is a powerful Python-based image viewer. It uses dcm2niix to handle DICOM files through its fslpy libraries.
• Functional Real-Time Interactive Endogenous Neuromodulation and Decoding (FRIEND) Engine uses dcm2niix.
• HABIT tumor analysis.
• HCF-bidser Jupyter notebook script for DICOM to BIDS format.
• heudiconv can use dcm2niix to create BIDS datasets. Data acquired using the reproin convention can be easily converted to BIDS.
• Horos (Osirix) Bids Output Extension is a OsiriX / Horos plugin that uses dcm2niix for creating BIDS output.
• kipettools uses dcm2niix to load PET data.
• LEAD-DBS uses dcm2niix for DICOM import.
• lin4neuro releases such as the English l4n-18.04.4-amd64-20200801-en.ova include MRIcroGL and dcm2niix pre-installed. This allows user with VirtualBox or VMWarePlayer to use these tools (and many other neuroimaging tools) in a graphical virtual machine.
• mercure-dcm2bids is a Mercure module to perform DICOM to BIDS conversion using dcm2bids and dcm2niix.
• micapipe generates modality based connectomes.
• mri_convert is part of the popular FreeSurfer package and wraps dcm2niix to improve DICOM support.
• MRIcroGL is available for MacOS, Linux and Windows and provides a graphical interface for dcm2niix. You can get compiled copies from the MRIcroGL NITRC web site.
• MrPyConvert Python library dicom to bids conversion.
• musclemap-webapp whole-body muscle segmentation using a MONAI 2D UNet model.
• Nekton is a python package for DICOM to NifTi and NifTi to DICOM-SEG and GSPS conversion.
• NeuroClaw AI for reproducible neuroimaging includes dcm2niix skills.
• neuro_docker includes dcm2niix as part of a single, static Dockerfile.
• NeuroDebian provides up-to-date version of dcm2niix for Debian-based systems.
• neurodocker includes dcm2niix as a lean, minimal install Dockerfile.
• NeuroElf can use dcm2niix to convert DICOM images.
• Neuroinformatics Database (NiDB) is designed to store, retrieve, analyze, and share neuroimaging data. It uses dcm2niix for image QA and handling some formats.
• neurospin_to_bids for exporting imaging data from the NeuroSpin archive in BIDS format.
• NiftyPET provides PET image reconstruction and analysis, and uses dcm2niix to handle DICOM images.
• niix2bids attempts to automatically convert Siemens MRI images converted by dcm2niix to BIDS.
• nipoppy uses dcm2niix (via dcm2bids).
• nipype can use dcm2niix to convert images.
• PET2BIDS uses dcm2niix for DICOM images.
• pl-dcm2niix is a ChRIS wrapper for dcm2niix.
• py2bids dcm2niix dicom to bids conversion wrapper.
• pyBIDSconv provides a graphical format for converting DICOM images to the BIDS format. It includes clever default heuristics for identifying Siemens scans.
• pydcm2niix is a Python module for working with dcm2niix.
• pydra-dcm2bids supports Pydra tasks for dcm2bids.
• pydra-dcm2niix is a contains Pydra task interface for dcm2niix.
• qsm Quantitative Susceptibility Mapping software.
• qsmbly browser-based quantitative susceptibility mapping.
• QSMxT is an end-to-end software toolbox for Quantitative Susceptibility Mapping.
• qunex Quantitative Neuroimaging Environment & ToolboX for data organization, preprocessing, and quality assurance neuroimaging modalities.
• reproin is a setup for automatic generation of shareable, version-controlled BIDS datasets from MR scanners.
• Retina_OCT_dcm2nii converts optical coherence tomography (OCT) data to NIfTI.
• sci-tran dcm2niix Flywheel Gear (docker).
• seedseg segmentation of gold fiducial markers in T1-weighted prostate MRI.
• SHAring iN vivO Imaging Resources (Shanoir) includes dcm2niix.
• shimming-toolbox enabled static and real-time shimming, using dcm2niix to import DICOM data.
• SlicerDcm2nii is an extension to import DICOM data into 3D Slicer.
• spinalcordtoolbox-webapp MRI segmentation interface for Spinal Cord Toolbox.
• tar2bids converts DICOM tarball(s) to BIDS using heudiconv which invokes dcm2niix.
• TORTOISE is used for processing diffusion MRI data, and uses dcm2niix to import DICOM images.
• TractoR (Tracto­graphy with R) uses dcm2niix for image conversion.
• twice_exceptionality_repository converts DICOM to BIDS format, creates masks, and runs VBM.
• vesselboost-webapp blood vessel segmentation.
• XA30_workaround uses dcm2niix.
• XNAT2BIDS is a simple xnat pipeline to convert DICOM scans to BIDS-compatible output.