Quick Start Guide

pip install dcm2niix

dcm2niix --version

from dcm2niix import __version__, bin
print(f"dcm2niix version: {__version__}")
print(f"Binary location: {bin}")

from dcm2niix import main

# Convert DICOM folder to NIfTI
exit_code = main(["/path/to/dicom/folder"])

if exit_code == 0:
    print("Conversion successful!")
else:
    print(f"Conversion failed with exit code {exit_code}")

# Convert DICOM folder (output to same directory)
dcm2niix /path/to/dicom/folder

# Specify output directory
dcm2niix -o /output/nifti /input/dicom

from dcm2niix import main

exit_code = main([
    "-z", "y",                    # Enable gzip compression
    "-b", "y",                    # Generate BIDS JSON sidecar
    "-ba", "y",                   # Anonymize patient info
    "-o", "/bids/output",         # Output directory
    "/dicom/input"                # Input directory
])

dcm2niix -z y -b y -ba y -o /bids/output /dicom/input

from dcm2niix import main

# Use protocol name and series number for filenames
exit_code = main([
    "-f", "%p_%s",                # Filename: protocol_series
    "-o", "/output",
    "/input"
])
# Output: T1_MPRAGE_5.nii

dcm2niix -f %p_%s -o /output /input

# Step 1: List available series with CRC values
dcm2niix -q l /dicom/folder

# Step 2: Convert only desired series
dcm2niix -n 52301 -n 52305 /dicom/folder

from dcm2niix import main

# Convert specific series by CRC
exit_code = main([
    "-n", "52301",                # First series CRC
    "-n", "52305",                # Second series CRC
    "/dicom/folder"
])

from dcm2niix import main

# Skip derived images, localizers, and scouts
exit_code = main([
    "-i", "y",                    # Ignore derived/localizer
    "-z", "y",                    # Compress output
    "/input/folder"
])

dcm2niix -i y -z y /input/folder

from dcm2niix import main
from pathlib import Path

# Process all subjects in a directory
input_root = Path("/data/dicom")
output_root = Path("/data/nifti")

for subject_dir in input_root.iterdir():
    if subject_dir.is_dir():
        subject_id = subject_dir.name
        output_dir = output_root / subject_id
        output_dir.mkdir(parents=True, exist_ok=True)
        
        exit_code = main([
            "-z", "y",
            "-b", "y",
            "-ba", "y",
            "-f", f"sub-{subject_id}_%p_%s",
            "-o", str(output_dir),
            str(subject_dir)
        ])
        
        print(f"Subject {subject_id}: {'Success' if exit_code == 0 else f'Failed ({exit_code})'}")

from dcm2niix import main

# Enable verbose output to see detailed information
exit_code = main([
    "-v", "2",                    # Maximum verbosity
    "/input/folder"
])

dcm2niix -v 2 /input/folder

from dcm2niix import main

exit_code = main(["/input/folder"])

if exit_code == 0:
    print("Success: All files converted")
elif exit_code == 2:
    print("Error: No valid DICOM files found")
elif exit_code == 4:
    print("Error: Corrupt DICOM file detected")
elif exit_code == 5:
    print("Error: Input folder invalid")
elif exit_code == 6:
    print("Error: Output folder invalid")
elif exit_code == 8:
    print("Warning: Partial success - some files converted")
else:
    print(f"Error: Conversion failed with exit code {exit_code}")

from dcm2niix import main
import subprocess

try:
    exit_code = main(
        ["-v", "1", "/input/folder"],
        capture_output=True,
        text=True,
        timeout=300
    )
    
    if exit_code != 0:
        print(f"Conversion failed with exit code {exit_code}")
        
except subprocess.TimeoutExpired:
    print("Conversion timed out after 300 seconds")
except Exception as e:
    print(f"Unexpected error: {e}")

# Install pigz first
# macOS: brew install pigz
# Ubuntu: sudo apt-get install pigz

# Use pigz for parallel compression
dcm2niix -z y -9 /input/folder

from dcm2niix import main

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

# Use internal compression (no pigz required)
dcm2niix -z i /input/folder

# Fastest I/O, larger files
dcm2niix -z n /input/folder

dcm2niix -e n -z y /input/folder

dcm2niix -e y /input/folder

dcm2niix -e o -z y /input/folder

from dcm2niix import main

# Use precise float scaling (critical for quantitative work)
exit_code = main([
    "-p", "y",                    # Precise float scaling
    "-l", "o",                    # Preserve original values
    "-z", "y",                    # Compress output
    "/philips/dwi/folder"
])

dcm2niix -p y -l o -z y /philips/dwi/folder