Command-Line Options

Complete reference for all dcm2niix command-line options. All options can be passed through the Python API via main(args=[...]).

Usage

dcm2niix [options] <in_folder>

Quick Reference Table

Capabilities

Compression Options

Control output file compression.

-1

-2

-3

-4

-5

-6

-7

-8

-9

Gzip compression level (1=fastest, 9=smallest). Default: 6.

Usage:

dcm2niix -9 -z y /input/folder

Performance Impact:

• Level 1: ~10% better than uncompressed (fastest)
• Level 6: ~50% better than uncompressed (default balance)
• Level 9: ~52% better than uncompressed (slowest, marginally smaller)

Recommendation: Use default (6) unless storage is critical (then use 9).

-z <y/i/n/3/o>

Gzip compression mode:

• y = use pigz (parallel gzip, fastest)
• i = internal compression (miniz or zlib)
• n = no compression
• 3 = no compression, force 3D output
• o = optimal pigz (Unix only, auto-selects best method)

Default: n (no compression).

Mode Comparison:

Installation:

# macOS
brew install pigz

# Ubuntu/Debian
sudo apt-get install pigz

# CentOS/RHEL
sudo yum install pigz

Python Usage:

from dcm2niix import main

# Use pigz compression
exit_code = main(["-z", "y", "-9", "/input/folder"])

Output Directory and Format

Specify where files are saved and in what format.

-o <directory>

Output directory path. If omitted, files are saved to the input folder.

Behavior:

• Directory created automatically if it doesn't exist (parent must exist)
• Must have write permissions
• Can be relative or absolute path
• Exit code 6 if directory cannot be created
• Exit code 7 if directory is read-only

Examples:

# Absolute path
dcm2niix -o /data/nifti/output /data/dicom/input

# Relative path
dcm2niix -o ./output ./input

# Same as input (default)
dcm2niix /data/dicom

Python Usage:

from dcm2niix import main
from pathlib import Path

output_dir = Path("/output/nifti")
output_dir.mkdir(parents=True, exist_ok=True)

exit_code = main(["-o", str(output_dir), "/input/dicom"])

-e <format>

Export format:

• n = NIfTI (.nii or .nii.gz, default)
• y = NRRD (.nrrd, N-dimensional rectilinear grid)
• o = MGH/MGZ (.mgh/.mgz, FreeSurfer format)
• j = JNIfTI (.jnii, JSON-based NIfTI, requires compile support)
• b = BJNIfTI (.bnii, Binary JSON NIfTI, requires compile support)

Default: n (NIfTI).

Format Details:

Examples:

# NIfTI (default)
dcm2niix -e n -z y /input

# NRRD for visualization
dcm2niix -e y /input

# MGH for FreeSurfer
dcm2niix -e o -z y /input

Python Usage:

from dcm2niix import main

# Export to MGH format
exit_code = main(["-e", "o", "/freesurfer/input"])

File Naming

Customize output filenames using pattern templates.

-f <pattern>

Filename pattern using placeholders. Default: %f_%p_%t_%s (folder_protocol_time_series).

Available Placeholders:

Patient Identifiers (anonymized when -ba y):

• %i = Patient ID (0010,0020)
• %n = Patient name (0010,0010)
• %w = Weird/personal data (DOB, gender, weight, institution - PHI)

Study Identifiers:

• %g = Accession number (0008,0050)
• %x = Study ID (0020,0010)
• %k = Study instance UID (0020,000D)
• %t = Study time (formatted from 0008,0020 and 0008,0030)
• %l = Local procedure step description (0040,0254)

Series Identifiers:

• %s = Series number (0020,0011)
• %j = Series instance UID (0020,000E)
• %d = Series description (0008,103E)
• %p = Protocol name (0018,1030)
• %z = Sequence name (0018,0024)
• %q = Sequence number (if compiled with mySegmentByAcq)

Instance Identifiers:

• %r = Instance number (0020,0013)
• %u = Acquisition number (0020,0012)
• %e = Echo number (0018,0086)
• %y = Youth in series (GE RawDataRunNumber or TemporalPosition)

Hardware Identifiers:

• %m = Manufacturer (short: GE, Ph, Si, To, UI, NA)
• %v = Vendor (long: Siemens, Philips, GE, etc.)
• %a = Antenna/coil name (Siemens-specific, 0051,100F)

File/Folder Identifiers:

• %f = Folder name (directory containing first DICOM)
• %b = Basename (filename of first DICOM file)

Other:

• %c = Comments (DICOM tag 0020,4000)
• %h = Hazardous/experimental BIDS naming (ReproIn format)
• %o = Media object instance UID (0002,0003)

Pattern Examples:

# Simple: protocol and series number
dcm2niix -f %p_%s /input
# Output: T1_MPRAGE_5.nii

# BIDS-style with subject
dcm2niix -f sub-%i_%p /input
# Output: sub-12345_T1_MPRAGE.nii

# Detailed with timestamp
dcm2niix -f %p_%t_%s_%e /input
# Output: T1_MPRAGE_20230115143022_5_1.nii

# Manufacturer and protocol
dcm2niix -f %m_%v_%p /input
# Output: Si_Siemens_T1_MPRAGE.nii

Python Usage:

from dcm2niix import main

# BIDS-compliant naming
exit_code = main([
    "-f", "sub-%i_ses-%x_%p_%s",
    "-o", "/bids/output",
    "/dicom/input"
])

Warning about PHI:

• %w includes DOB, gender, weight - contains PHI (Protected Health Information)
• %i and %n are patient identifiers - use -ba y to anonymize
• For BIDS compliance, use -ba y and -bi to override subject ID

-w <0/1/2>

Name conflict behavior when output file already exists:

• 0 = skip duplicates (don't convert)
• 1 = overwrite existing file
• 2 = add suffix to create new file (default)

Default: 2 (add suffix).

Behavior Details:

Suffix Pattern:

• First duplicate: filename_i.nii
• Second duplicate: filename_j.nii
• Third duplicate: filename_k.nii
• Continues through alphabet

Examples:

# Skip existing files (fast re-run)
dcm2niix -w 0 /input

# Overwrite existing files
dcm2niix -w 1 /input

# Create new files with suffix (default)
dcm2niix -w 2 /input

Python Usage:

from dcm2niix import main

# Only convert new files
exit_code = main(["-w", "0", "/input"])

# Exit code 0 even if files were skipped

--terse

Omit filename postfixes for multi-volume datasets.

Warning: Can cause files to overwrite each other if multiple volumes exist.

Disabled Postfixes:

• _e1, _e2 (multi-echo)
• _c1, _c2 (multi-coil)
• _i, _j (name conflicts)
• _r1, _r2 (multiple repetition times)

Retained Postfixes:

• _real, _imaginary, _ph (complex data - essential)
• _ADC, _fieldmaphz (derived volumes - essential)
• _MoCo, _Eq, _Tilt (processing indicators - important)

Use Case: Single-echo, single-volume datasets where postfixes are redundant.

Example:

# Without --terse (default)
dcm2niix /single/echo/t1
# Output: T1_MPRAGE_5.nii

# With --terse
dcm2niix --terse -f %p /single/echo/t1
# Output: T1_MPRAGE.nii

Python Usage:

from dcm2niix import main

exit_code = main(["--terse", "-f", "%p", "/input"])

BIDS Options

Brain Imaging Data Structure (BIDS) compliance.

-b <y/n/o>

BIDS JSON sidecar generation:

• y = create JSON sidecar alongside NIfTI (default)
• n = no JSON sidecar
• o = only JSON, no NIfTI file

Default: y.

JSON Sidecar Contains:

• Acquisition parameters (TR, TE, flip angle, etc.)
• Equipment information (manufacturer, model, field strength)
• Patient demographics (if not anonymized)
• Timing information
• Vendor-specific metadata
• Image geometry and orientation

Mode Comparison:

Examples:

# Standard BIDS (default)
dcm2niix -b y /input

# No JSON metadata
dcm2niix -b n /input

# Only extract metadata
dcm2niix -b o /input

Python Usage:

from dcm2niix import main

# Metadata extraction only
exit_code = main(["-b", "o", "/input"])
# Creates .json files, no .nii files

-ba <y/n>

Anonymize BIDS JSON output by removing patient identifying information. Default: y (anonymize).

Removed Fields When Enabled:

• PatientName
• PatientID
• PatientBirthDate
• SeriesInstanceUID
• StudyInstanceUID
• StudyID
• AccessionNumber
• ReferringPhysicianName
• AcquisitionDate (changed to AcquisitionTime only)
• AcquisitionDateTime

Retained Fields:

• All acquisition parameters
• Equipment information
• Image geometry
• Timing (relative, not absolute dates)

Examples:

# Anonymized (default)
dcm2niix -ba y /input

# Include patient info
dcm2niix -ba n /input

Python Usage:

from dcm2niix import main

# Non-anonymized for internal use
exit_code = main(["-b", "y", "-ba", "n", "/internal/data"])

HIPAA Compliance: -ba y removes direct identifiers but may not fully de-identify data. Review HIPAA Safe Harbor or Expert Determination methods for complete de-identification.

-bi <subject_id>

BIDS subject ID override. Sets the subject identifier in output filenames and JSON metadata.

Effect:

• Overrides automatic subject ID extraction from DICOM
• Can be used with -f filename pattern for BIDS naming
• Stored in JSON metadata (if -b y)

Example:

# Set subject ID
dcm2niix -bi sub-001 -f sub-%bi_%p /input
# Output: sub-sub-001_T1_MPRAGE.nii

# Better: let -f handle prefix
dcm2niix -bi 001 -f sub-%bi_%p /input
# Output: sub-001_T1_MPRAGE.nii

Python Usage:

from dcm2niix import main

subject_ids = ["001", "002", "003"]
for subj in subject_ids:
    exit_code = main([
        "-bi", f"sub-{subj}",
        "-f", f"sub-{subj}_%p",
        "-o", f"/bids/sub-{subj}",
        f"/dicom/{subj}"
    ])

-bv <session_id>

BIDS session/visit identifier. Sets the session identifier in output filenames and JSON metadata.

Effect:

• Adds session information to metadata
• Used for longitudinal studies with multiple visits
• Can be combined with -bi for full BIDS paths

Example:

# Set session ID
dcm2niix -bi 001 -bv ses-01 -f sub-%bi_%bv_%p /input
# Output: sub-001_ses-01_T1_MPRAGE.nii

Python Usage:

from dcm2niix import main

# Multi-session study
for subject in subjects:
    for session in sessions:
        exit_code = main([
            "-bi", subject,
            "-bv", session,
            "-f", f"sub-{subject}_ses-{session}_%p",
            "-o", f"/bids/sub-{subject}/ses-{session}",
            f"/dicom/{subject}/{session}"
        ])

Search and Discovery

Control how dcm2niix searches for DICOM files.

-d <0-9>

Directory search depth. How many levels deep to search for DICOM files in subdirectories. Default: 5.

Values:

• 0 = only search specified folder, no subdirectories
• 1-9 = search N levels deep

Performance Impact:

• Shallow search (0-1): Fast, suitable for organized data
• Medium search (2-5): Balanced, default
• Deep search (6-9): Slow, for deeply nested structures

Examples:

# Flat directory
dcm2niix -d 0 /flat/dicom/folder

# Deep nesting
dcm2niix -d 9 /deeply/nested/structure

Python Usage:

from dcm2niix import main

# Fast conversion of organized data
exit_code = main(["-d", "1", "/organized/pacs/export"])

-a <y/n>

Adjacent DICOMs mode. When enabled, assumes all images from the same series are in the same folder, allowing faster conversion. Default: n (search all folders).

Behavior:

When to Use:

• y: PACS exports where each series has its own subfolder
• n: Mixed data, unknown organization, research archives

Examples:

# Fast mode for PACS export
dcm2niix -a y -d 1 /pacs/export

# Safe mode for mixed data
dcm2niix -a n -d 5 /research/archive

Python Usage:

from dcm2niix import main

# Optimized for organized PACS data
exit_code = main(["-a", "y", "-d", "1", "/pacs/export"])

-q <y/l/n>

Directory search reporting:

• y = show number of DICOMs found (default)
• l = list all DICOM files found with details (including CRC)
• n = no search reporting (quiet)

Default: y.

List Mode Output Format:

Found 240 DICOM files in /dicom/folder
Series 001: T1_MPRAGE [52301] - 176 files
Series 002: T2_FLAIR [52305] - 32 files
Series 003: BOLD_fMRI [52310] - 240 files

Use Cases:

• y: Standard feedback
• l: Identify series CRC for selective conversion
• n: Batch processing scripts, minimal output

Examples:

# List all series with CRC values
dcm2niix -q l /dicom/folder

# Quiet mode for scripts
dcm2niix -q n /dicom/folder

Python Usage:

from dcm2niix import main
import re

# Get series list
result = subprocess.run(
    [bin, "-q", "l", "/dicom/folder"],
    capture_output=True,
    text=True
)

# Parse CRC values
series_crcs = re.findall(r'\[(\d+)\]', result.stdout)

-s <y/n>

Single file mode. Only convert the specified DICOM file, don't search for other files in the folder. Default: n.

Behavior:

• y: Convert only the specified file (may be incomplete if part of series)
• n: Search folder for related files to build complete volume

Use Cases:

• Testing conversion on single image
• Converting single-slice localizers
• Quick format validation

Warning: Output may be incomplete if the file is part of a multi-slice volume.

Examples:

# Convert single file
dcm2niix -s y /path/to/image.dcm

# Convert complete series (default)
dcm2niix -s n /path/to/folder

Python Usage:

from dcm2niix import main

# Test single DICOM file
exit_code = main(["-s", "y", "/test/sample.dcm"])

Series Selection and Filtering

Filter which images are converted.

-n <CRC>

Only convert series matching this CRC number. Can be specified up to 16 times to convert multiple specific series.

Workflow:

1. Use -q l to list series and their CRC values
2. Identify desired series CRC numbers
3. Use -n <CRC> to convert only those series

Examples:

# Step 1: List series
dcm2niix -q l /dicom/folder
# Output shows: Series 001: T1_MPRAGE [52301]

# Step 2: Convert specific series
dcm2niix -n 52301 /dicom/folder

# Multiple series
dcm2niix -n 52301 -n 52305 -n 52310 /dicom/folder

Python Usage:

from dcm2niix import main

# Convert multiple specific series
series_to_convert = ["52301", "52305", "52310"]
args = []
for crc in series_to_convert:
    args.extend(["-n", crc])
args.append("/dicom/folder")

exit_code = main(args)

-i <y/n>

Ignore derived, localizer, and 2D images. When enabled, skips secondary captures, scout images, and 2D slices. Default: n (include all images).

Filtered Image Types:

• Derived images (ImageType contains "DERIVED")
• Localizer/scout images (ImageType contains "LOCALIZER")
• 2D single-slice images (when 3D volume expected)
• Secondary captures
• Screen saves

Use Cases:

• Clean up large datasets with many scouts
• Focus on primary acquisitions only
• Reduce output clutter

Examples:

# Include all images (default)
dcm2niix -i n /mixed/data

# Ignore derived and scouts
dcm2niix -i y /mixed/data

Python Usage:

from dcm2niix import main

# Clean conversion, primary sequences only
exit_code = main(["-i", "y", "/pacs/export"])

-m <n/y/0/1/2>

Merge 2D slices from the same series:

• n or 0 = don't merge slices, create separate file for each slice
• y or 1 = merge all slices from series into volume
• 2 = auto mode (default, smart merging)

Default: 2 (auto).

Auto Mode Logic:

• Merges slices when they form consistent 3D/4D volume
• Keeps separate when parameters differ:
  • Different echo times
  • Different acquisition times (beyond threshold)
  • Different orientations
  • Different exposure settings (CT)

Use Cases:

• n: Manual inspection, quality control
• y: Force merge despite parameter variations (use with caution)
• 2: Recommended, intelligent merging

Examples:

# Don't merge, one file per slice
dcm2niix -m n /2d/slices

# Force merge all
dcm2niix -m y /2d/slices

# Auto mode (default)
dcm2niix -m 2 /2d/slices

Python Usage:

from dcm2niix import main

# Keep slices separate for QC
exit_code = main(["-m", "n", "/qc/slices"])

Image Processing

Options affecting image data processing.

-l <y/n/o>

16-bit integer range scaling:

• y = losslessly scale to use full dynamic range (INT16: -32768 to 32767)
• n = no scaling, but convert UINT16 to INT16
• o = original, preserve exact values and data type (default)

Default: o (original).

Mode Comparison:

Important: Mode y is lossless - original values can be recovered using stored scale factors in NIfTI header.

Examples:

# Preserve exact pixel values (default)
dcm2niix -l o /quant/analysis

# Maximize dynamic range
dcm2niix -l y /visualization

Python Usage:

from dcm2niix import main

# Quantitative analysis - preserve exact values
exit_code = main(["-l", "o", "/dwi/data"])

-x <y/n/i>

Crop 3D acquisitions:

• y = crop excess slices from 3D volumes
• n = don't crop (default)
• i = ignore (neither crop nor rotate 3D acquisitions)

Default: n.

What Cropping Does:

• Detects padding slices added by scanner
• Removes non-zero content boundaries
• Reduces file size
• Improves alignment

Mode Comparison:

Examples:

# Crop excess slices
dcm2niix -x y /3d/mprage

# Keep all slices (default)
dcm2niix -x n /3d/mprage

# No processing
dcm2niix -x i /3d/mprage

Python Usage:

from dcm2niix import main

# Crop 3D structural scans
exit_code = main(["-x", "y", "/structural/t1"])

-p <y/n>

Philips precise float scaling. Use true floating-point values rather than display scaling. Default: y (use precise scaling).

Scaling Types:

Critical for:

• Quantitative DWI/DTI (ADC values)
• T1/T2 mapping
• Pharmacokinetic modeling
• Any quantitative Philips data

Examples:

# Precise scaling (default, recommended)
dcm2niix -p y /philips/dwi

# Display scaling (not recommended)
dcm2niix -p n /philips/visual

Python Usage:

from dcm2niix import main

# Quantitative Philips DWI - must use precise scaling
exit_code = main(["-p", "y", "-l", "o", "/philips/dwi"])

Metadata Options

Control metadata handling.

-c <text>

Comment string stored in NIfTI aux_file field (maximum 24 characters). Use empty string "" to anonymize the comment field (0020,4000).

Storage:

• NIfTI aux_file field (24 char limit)
• JSON "ConversionComments" field (full text)

Examples:

# Add study identifier
dcm2niix -c "VIP_Study" /input

# Anonymize comment field
dcm2niix -c "" /input

# Project and visit
dcm2niix -c "PRJ_001_V1" /input

Python Usage:

from dcm2niix import main

# Add study code
exit_code = main(["-c", "STUDY_XYZ", "-b", "y", "/input"])

Operational Modes

Special operational modes.

-r <y/n>

Rename mode. Rename DICOM files using the naming pattern instead of converting them. Default: n (convert).

Behavior:

• DICOM files renamed in place
• No NIfTI conversion performed
• Uses -f pattern for new names
• Useful for organizing DICOM archives

Examples:

# Rename DICOMs without converting
dcm2niix -r y -f %p_%s /dicom/folder

Python Usage:

from dcm2niix import main

# Organize DICOM archive
exit_code = main(["-r", "y", "-f", "%p_%s_%i", "/archive"])

-g <y/n/o/i>

Generate defaults file:

• y = generate configuration file
• n = don't generate (default)
• o = only (reset and write defaults, don't convert)
• i = ignore (reset to defaults, then proceed with conversion)

Default: n.

Configuration File Location:

• Unix/macOS: ~/.dcm2nii.ini or similar
• Windows: Registry key HKEY_CURRENT_USER\Software\dcm2nii

Examples:

# Generate config file
dcm2niix -g y /input

# Reset to defaults and convert
dcm2niix -g i /input

Output Control

Control console output verbosity.

-v <n/y/0/1/2>

Verbose output level:

• n or 0 = minimal output, errors only (default)
• y or 1 = standard output with warnings
• 2 = logorrheic (verbose debugging information)

Default: 0 (minimal).

Level Comparison:

Examples:

# Minimal output (default)
dcm2niix -v 0 /input

# Standard verbosity
dcm2niix -v 1 /input

# Debug mode
dcm2niix -v 2 /input

Python Usage:

from dcm2niix import main

# Debug conversion issues
exit_code = main(["-v", "2", "/problem/folder"], capture_output=True, text=True)

--progress <y/n>

Report progress information in Slicer format. Default: n.

Output Format:

• Compatible with 3D Slicer progress reporting
• XML-formatted progress tags

Example:

dcm2niix --progress y /input

Byte Order

Control output byte order.

--big-endian <y/n/o>

Byte order for NIfTI output:

• y = big-endian (byte-swapped on x86/x64)
• n = little-endian
• o = optimal/native (default, matches platform)

Default: o (native).

Recommendation: Use default (o) unless specific compatibility required.

Example:

# Force big-endian
dcm2niix --big-endian y /input

Image Orientation

Control image axis orientation.

-y <y/n>

Flip Y-axis (rows):

• y = flip rows (non-standard)
• n = don't flip (default, standard RAS+ orientation)

Default: n (standard RAS+ orientation).

Note: Default behavior already applies proper DICOM LPS to NIfTI RAS+ conversion. This option provides additional control for edge cases only.

Example:

# Standard orientation (default)
dcm2niix -y n /input

Advanced Options

Specialized options for edge cases.

-j <y/n>

Compare GE slice timing from DICOM tag (0021,105E). For debugging and validation of GE diffusion sequences. Default: n.

--ignore_trigger_times

Disregard DICOM trigger time tags (0018,1060 and 0020,9153). Useful when trigger timing is incorrect or unreliable.

--diffCyclingModeGE <0/1/2/3>

GE diffusion gradient cycling mode override. Typically auto-detected. Values: 0-3 (undocumented, for advanced users).

Example:

dcm2niix --diffCyclingModeGE 0 /ge/dwi/folder

--xml

Enable Slicer XML format features for integration with 3D Slicer.

Help and Version

Information commands.

-h

Show help message with all options and exit.

Example:

dcm2niix -h

--version

Report dcm2niix version information and exit.

Output Includes:

• Version string
• Compiler used
• Platform (x86-64, ARM, etc.)
• Operating system
• Optional features (JPEGLS, JP2, etc.)

Example:

dcm2niix --version

Python Usage:

from dcm2niix import main

# Returns exit code 3 (version report)
exit_code = main(["--version"])

-u

Up-to-date version check (Unix/macOS only). Checks GitHub for the latest release and reports if update is available.

Example:

dcm2niix -u

Option Combinations

Common Workflows

BIDS-Compliant Research Dataset:

dcm2niix -z y -b y -ba y -i y -f sub-%i_%p -o /bids/output /dicom/input

High-Quality Quantitative Analysis:

dcm2niix -l o -p y -x n -b y -o /analysis/output /philips/input

Fast Batch Processing:

dcm2niix -z y -a y -d 1 -i y -w 0 -v 0 -o /output /organized/input

Debugging Conversion Issues:

dcm2niix -v 2 -q l -m 2 /problem/folder

Minimal Output for Visualization:

dcm2niix -z y -l y -b n -i y -o /viz/output /input

Configuration File

On Unix/macOS systems, default settings can be stored in a configuration file. Location varies by platform.

Generate Configuration:

dcm2niix -g o

Reset to Defaults:

dcm2niix -g i /input

Windows Configuration: Stored in registry: HKEY_CURRENT_USER\Software\dcm2nii

See Also

• Python API - Programmatic usage from Python
• BIDS JSON Metadata - JSON sidecar format and fields
• Output Formats - File formats and naming patterns
• Image Processing - Processing features and algorithms
• Filtering - Series selection and filtering strategies