Install & Compatibility
Where this runs
tested against v5.4.6 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
build_error
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 9.5s · import 0.403s · 528MB
536MB installed
● package 536MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
itk
✓ import itk
✗ import itk_core
Even when installing 'itk-core', the Python module is exposed under the 'itk' namespace.
ImageFileReader
✓ import itk
reader = itk.ImageFileReader[itk.Image[itk.F, 3]].New()
✗ from itk.io import ImageFileReader
Most ITK classes are directly accessible via the top-level 'itk' namespace; avoid trying to guess submodules.
This quickstart demonstrates how to read an N-dimensional image, apply a common filter (Gaussian smoothing), and write the result back to disk using `itk-core`'s Python bindings. It includes setup for creating a dummy image if no input file exists, making it runnable out-of-the-box.
import itk
import numpy as np
import os
# --- Setup: Create a dummy image if 'input.mha' doesn't exist ---
input_file = "input.mha"
output_file = "output_smoothed.mha"
if not os.path.exists(input_file):
print(f"{input_file} not found, creating a dummy 3D image for demonstration.")
array_image = np.zeros((64, 64, 64), dtype=np.float32)
# Add a simple cube to the image
array_image[10:50, 10:50, 10:50] = 100.0
dummy_image = itk.image_from_array(array_image)
# Set metadata (origin, spacing) which is important for ITK images
dummy_image.SetSpacing([1.0, 1.0, 1.0])
dummy_image.SetOrigin([0.0, 0.0, 0.0])
itk.imwrite(dummy_image, input_file)
print(f"Created {input_file}")
# --- Core ITK Usage: Read, Process, Write ---
# 1. Define the image type (e.g., 3D float image)
ImageType = itk.Image[itk.F, 3] # itk.F for float, 3 for 3 dimensions
# 2. Read an image
print(f"Reading image from {input_file}...")
image = itk.imread(input_file, ImageType)
print(f"Original image size: {image.GetLargestPossibleRegion().GetSize()}")
# 3. Apply a filter (e.g., Gaussian smoothing)
print("Applying Gaussian filter...")
gaussian_filter = itk.GaussianImageFilter[ImageType, ImageType].New()
gaussian_filter.SetInput(image)
gaussian_filter.SetSigma(2.0) # Set the standard deviation for the Gaussian kernel
gaussian_filter.Update() # Execute the filter
smoothed_image = gaussian_filter.GetOutput()
# 4. Write the processed image
print(f"Writing smoothed image to {output_file}...")
itk.imwrite(smoothed_image, output_file)
print(f"Smoothed image size: {smoothed_image.GetLargestPossibleRegion().GetSize()}")
print("Image processing complete.")
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'itk_core'
Attempting to import the Python module using the PyPI package name `itk_core`.
fixThe correct import for ITK core functionality is `import itk`, regardless of whether `itk-core` or `itk` was installed via pip.
itk.Exception: Image dimension mismatch
Applying an ITK filter or operation that expects a specific image dimension (e.g., 3D) to an image of a different dimension (e.g., 2D), or mismatching dimensions in image processing pipelines.
fixEnsure that your input images and chosen filters operate on consistent dimensions. Explicitly define `ImageType` using `itk.Image[itk.F, N_DIMENSIONS]` where `N_DIMENSIONS` matches your image data.
MemoryError: Unable to allocate XXXXX bytes
Attempting to load or process an image that exceeds available system memory, often with large 3D/4D datasets or when copying images to/from NumPy arrays.
fixReduce image size, process in smaller regions, use memory-efficient data types (e.g., `itk.UC` for `unsigned char`), or upgrade system RAM. Be mindful when converting between `itk.Image` and `numpy.ndarray` as this can temporarily duplicate data.
Upgrade
Version history
5.4.6latest on PyPI · released Apr 23, 2026
Audit
Dependencies
No dependency data recorded yet.