Install & Compatibility
Where this runs
tested against v2.5.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.95 runs
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.2s · import 0.186s · 282MB
280MB installed
● package 280MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
SimpleITK
✓ import SimpleITK as sitk
✗ import simpleitk
The PyPI package name is lowercase ('simpleitk'), but the Python module to import uses camel case ('SimpleITK'). By convention, it's often aliased as 'sitk'.
This quickstart demonstrates how to create a SimpleITK image, set pixel values, apply a Gaussian smoothing filter, read a pixel value, and save the resulting image to disk. For visualization, external tools like ImageJ/Fiji are typically used via `sitk.Show()`.
import SimpleITK as sitk
# Create a 2D image (e.g., 64x64 pixels, 16-bit integer)
image_size = [64, 64]
image = sitk.Image(image_size, sitk.sitkInt16)
# Set some pixel values (e.g., a square in the middle)
# Note: SimpleITK indexing is (x,y,z), while numpy conversion often reverses axes.
image[10:50, 10:50] = 100
# Apply a Gaussian smoothing filter
gaussian_filter = sitk.SmoothingRecursiveGaussianImageFilter()
gaussian_filter.SetSigma(2.0) # Set the standard deviation of the Gaussian
smoothed_image = gaussian_filter.Execute(image)
# Get a pixel value at a specific index
pixel_value = smoothed_image.GetPixel((32, 32))
print(f"Pixel value at (32,32) after smoothing: {pixel_value}")
# Save the image (e.g., to a MetaImage file format)
sitk.WriteImage(smoothed_image, "smoothed_image.mha")
print("Saved smoothed_image.mha")
# To visualize the image, you would typically use an external viewer
# For example, if ImageJ/Fiji is installed and configured:
# sitk.Show(smoothed_image, 'Smoothed Image')
Debug
Known issues
breakingSimpleITK 2.0 removed the `Transform::AddTransform` method. Composite transformations are now handled by a dedicated `CompositeTransform` class, requiring explicit creation of this class instead of adding transforms to a generic `Transform` object.fixReplace `tx.AddTransform(tx1)` with `tx = sitk.CompositeTransform([tx1, tx2])`.
affects: 2.0.0 and later
breakingWith SimpleITK 2.0, filter `Execute` methods no longer accept parameters as arguments. All filter parameters must be set via their respective `SetXYZ` methods on the filter object before calling `Execute`.fixInstead of `filter.Execute(image, param1, param2)`, use `filter.SetParam1(param1); filter.SetParam2(param2); output = filter.Execute(image)`.
affects: 2.0.0 and later
gotchaWhen converting between a SimpleITK `Image` object and a NumPy array (e.g., using `sitk.GetArrayFromImage` or `sitk.GetImageFromArray`), the axis order is reversed. SimpleITK uses (x, y, z) indexing, while NumPy typically uses (z, y, x) (depth, rows, columns).fixBe mindful of axis order during conversion and adjust indexing or array reshaping accordingly. For a 3D image, SimpleITK's `image[x,y,z]` corresponds to NumPy's `np_array[z,y,x]`.
affects: All versions
gotchaOn Windows, importing SimpleITK may fail with `ImportError: DLL load failed while importing _SimpleITK: The specified module could not be found`. This often indicates missing Microsoft Visual C++ Redistributable packages.fixInstall the appropriate Microsoft Visual C++ Redistributable for Visual Studio package for your Python and SimpleITK build (e.g., for VS 2015-2022).
affects: All versions on Windows
gotchaSimpleITK does not include a built-in image viewer. While `sitk.Show()` can launch an external viewer (like ImageJ/Fiji), users might expect immediate visualization without additional software or configuration.fixInstall a compatible image viewer (e.g., ImageJ/Fiji) and configure environment variables if necessary for `sitk.Show()` to find it. Alternatively, convert SimpleITK images to NumPy arrays (`sitk.GetArrayFromImage`) and use plotting libraries like Matplotlib or specialized visualization tools.
affects: All versions
breakingSimpleITK 2.0 upgraded its underlying ITK dependency to version 5 (ITKv5). This major update brought numerous changes to ITK's internal workings and behaviors, which can indirectly affect SimpleITK users, especially those working with advanced features or custom ITK integrations.fixConsult the ITK v5 Migration Guide for details on underlying ITK changes. Review SimpleITK documentation and examples for compatible patterns.
affects: 2.0.0 and later
gotchaSome versions of SimpleITK, particularly when dealing with specific datasets, may encounter issues with non-orthonormal direction cosines, leading to errors like 'ITK only supports orthonormal direction cosines. No orthonormal definition found.' This can be problematic for certain medical imaging data.fixIf encountered, consider testing with SimpleITK 2.0.2 if possible, or preprocess images to ensure orthonormal direction cosines where applicable. The issue often relates to dataset specifics.
affects: Potentially 2.0.3 and higher, observed in 2.1.x
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'simpleitk'
The SimpleITK library is not installed in the current Python environment or the environment is not correctly activated.
fixInstall SimpleITK using `pip install SimpleITK` or `conda install -c simpleitk simpleitk`.
TypeError: argument must be simpleitk.Image, not numpy.ndarray
A SimpleITK function was called with a NumPy array when it expected a `simpleitk.Image` object.
fixConvert the NumPy array to a SimpleITK image using `sitk.GetImageFromArray(numpy_array)` before passing it to SimpleITK functions.
AttributeError: 'simpleitk.Image' object has no attribute 'shape'
SimpleITK `Image` objects do not directly expose NumPy array attributes like `shape` or `dtype` without explicit conversion.
fixConvert the SimpleITK image to a NumPy array using `numpy_array = sitk.GetArrayFromImage(sitk_image)` and then access `numpy_array.shape`.
RuntimeError: Exception thrown in SimpleITK ImageFileReader_Execute: ... (File not found/Unable to read)
The specified image file path is incorrect, the file does not exist, or the file is unreadable, corrupted, or in an unsupported format.
fixVerify the file path, ensure the file exists at the specified location, and confirm it is a valid, readable image file with a supported format.
Upgrade
Version history
2.5.6latest on PyPI · released Jul 30, 2026
Audit
Dependencies
No dependency data recorded yet.