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
py 3.10
✕ build_error
4/6 runs
py 3.11
✕ build_error
4/6 runs
py 3.12
✕ build_error
4/6 runs
py 3.13
✕ build_error
4/6 runs
py 3.9
✕ build_error
4/6 runs
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
itk
✓ import itk
✗ from itk_io import imread
All ITK Python functionality, including IO, is typically exposed directly under the top-level `itk` namespace. Direct imports from `itk_io` are generally not supported or necessary.
imread
✓ itk.imread
Convenience function for reading images, part of the ITK-IO functionality exposed via the main `itk` module.
imwrite
✓ itk.imwrite
Convenience function for writing images, part of the ITK-IO functionality exposed via the main `itk` module.
ImageFileReader
✓ itk.ImageFileReader
The core ITK C++ class binding for reading images, accessible through the `itk` namespace.
This quickstart demonstrates how to create a simple 3D image using NumPy, convert it to an ITK image object, save it to a MetaImage (.mha) file, and then read it back. Finally, it verifies the integrity of the data by converting it back to a NumPy array and comparing it with the original.
import itk
import numpy as np
import os
# 1. Create a dummy NumPy array (e.g., 3D unsigned char)
image_array = np.arange(64*64*64, dtype=np.uint8).reshape((64, 64, 64))
# 2. Convert NumPy array to ITK image object
itk_image = itk.image_from_array(image_array)
# Define a temporary file name for the image
output_filename = os.path.join(os.getcwd(), "itk_dummy_image.mha") # .mha is a common ITK format
# 3. Write the ITK image to a file using itk.imwrite
print(f"Writing image to {output_filename}")
itk.imwrite(itk_image, output_filename)
print("Image written successfully.")
# 4. Read the image back from the file using itk.imread
print(f"Reading image from {output_filename}")
read_itk_image = itk.imread(output_filename) # itk.imread infers pixel type if not specified
print("Image read successfully.")
# 5. Verify properties of the read image
print(f"Read image dimensions: {read_itk_image.GetImageDimension()}")
print(f"Read image size: {read_itk_image.GetLargestPossibleRegion().GetSize()}")
print(f"Read image pixel type: {read_itk_image.GetPixelIDTypeAsString()}")
# 6. (Optional) Convert the read ITK image back to a NumPy array for verification
read_array = itk.array_from_image(read_itk_image)
print(f"Read array shape: {read_array.shape}, dtype: {read_array.dtype}")
print(f"Arrays are equal: {np.array_equal(image_array, read_array)}")
# Clean up the dummy file
if os.path.exists(output_filename):
os.remove(output_filename)
print(f"Cleaned up {output_filename}")
itk-io --version
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'itk_io'
Attempted to import directly from 'itk_io' instead of the unified 'itk' namespace.
fixUse `import itk` to access all ITK functionality, including IO functions like `itk.imread`.
AttributeError: module 'itk' has no attribute 'imread'
The installed `itk` package (or its sub-packages) does not include the IO components required for `imread`/`imwrite`. This can happen if only a minimal `itk` version without IO support was installed, or if the `itk-io` component is missing.
fixEnsure you have `itk-io` installed (`pip install itk-io`) or install the full ITK package (`pip install itk` or `pip install itk-full`).
RuntimeError: itk::ImageIOBaseException (0x...): Could not read image file "path/to/image.dcm"
Generic error indicating ITK failed to read the image file. This could be due to the file not existing, corrupted data, an unsupported file format, or missing optional backend libraries (e.g., GDCM for DICOM, HDF5, etc.) required by ITK.
fixVerify the file path and existence. Check if the file is valid and not corrupted. If reading a specialized format like DICOM, ensure `itk-full` is installed (`pip install itk-full`) as it includes more IO backends. For custom builds, ensure relevant ITK modules are enabled.
TypeError: in method 'ImageFileReader_SetFileName', argument 2 of type 'char const *'
You are passing an object of an incorrect type (e.g., `pathlib.Path` object) to an ITK C++ binding method that specifically expects a Python string (which maps to `char const *` in C++).
fixConvert the path object to a string before passing it: `reader.SetFileName(str(my_path_object))`.
Upgrade
Version history
5.4.6latest on PyPI · released Apr 23, 2026
Audit
Dependencies
itkrequiredThe 'itk-io' package is part of the larger ITK ecosystem and relies on the core 'itk' package for fundamental image objects and processing. 'itk-io' internally depends on 'itk-core', which in turn depends on 'itk'.
numpyoptionalWhile not a strict dependency for 'itk-io' to run, 'numpy' is essential for practical Python usage of ITK, especially for converting between ITK image objects and NumPy arrays (e.g., via `itk.image_from_array`, `itk.array_from_image`).