This project configures pyproject.toml files and manages environmental variables needed to build ITK Python binary wheels on macOS, Linux, and Windows platforms. Scripts are available for both ITK infrastructure and ITK external module Python packages.

The Insight Toolkit (ITK) is an open-source, cross-platform system that provides developers with an extensive suite of software tools for image analysis. More information is available on the ITK website or at the ITK GitHub homepage.

• Building Remote Modules with ITKPythonPackage
• Building ITK Python Wheels
• Frequently Asked Questions
• Additional Information

ITK reusable workflows are available to build and package Python wheels as part of Continuous Integration (CI) via GitHub Actions runners. Those workflows can handle the overhead of fetching, configuring, and running ITKPythonPackage build scripts for most ITK external modules. See ITKRemoteModuleBuildTestPackageAction for more information.

For special cases where ITK reusable workflows are not a good fit, ITKPythonPackage scripts can be directly used to build Python wheels to target Windows, Linux, and macOS platforms. See below or the ITKPythonPackage ReadTheDocs documentation for more information on building wheels by hand.

Most users do not need to build ITK from source.

Pre-built ITK binaries are available as downloadable tarballs and the provided download-and-build shell scripts will fetch them automatically.

You may only need to build ITK yourself if you:

• Have a local ITK with custom patches or bug fixes not yet in a release
• Need to build against a specific unreleased commit
• Are developing ITK core itself

If none of the above apply to you, you may download an existing build of ITK from ITK's repository for ITK Python Builds. Or, use the download-and-build script seen in the Building Remote Module Wheels section below.

For more control over your builds, skip to The Build Process

• Python 3.10 or later
• Git
• Docker (for manylinux builds)
• Pixi package manager

Install Pixi:

# Linux or Mac
curl -fsSL https://pixi.sh/install.sh | bash

# Windows
powershell -ExecutionPolicy Bypass -c "irm -useb https://pixi.sh/install.ps1 | iex"

Clone the repo:

git clone https://github.com/InsightSoftwareConsortium/ITKPythonPackage.git
cd ITKPythonPackage

The build process calls build_wheels.py, which runs up to 7 steps:

1. Build SuperBuild support components
2. Build ITK C++ with Python wrapping
3. Build wheels for ITK C++
4. Fix up wheels if needed
5. Import test
6. (optional) Build a remote module against the ITK build
7. (optional) Build an ITK tarball cache

You can invoke the build_wheels.py script directly for more control shown below

Available pixi platform build environments:

# Building ITK Python Wheels on macOS for ITK v6.0b01
pixi run python3 scripts/build_wheels.py \
  --platform-env macosx-py310 \
  --itk-git-tag v6.0b01 \
  --no-build-itk-tarball-cache

Key options:

Run pixi run python3 scripts/build_wheels.py --help for the full option list.

To use the scripts that take care of the build for you, see this section:

cd ITKRemoteModule

bash dockcross-manylinux-download-cache-and-build-module-wheels.sh cp310

bash macpython-download-cache-and-build-module-wheels.sh 3.10

.\windows-download-cache-and-build-module-wheels.ps1 3.11

To see how to build wheels for your version of ITK see this section:

ITK_SOURCE_DIR=/path/to/your/ITK \
bash scripts/dockcross-manylinux-build-wheels.sh cp310

# Building on macOS with a specific git tag
pixi run python3 scripts/build_wheels.py \
  --platform-env macosx-py310 \
  --itk-source-dir /path/to/your/ITK \
  --itk-git-tag my-bugfix-branch \
  --no-build-itk-tarball-cache \
  --build-dir-root /tmp/itk-build

To see how to build ITK Python Build Caches, see this section:

bash scripts/make_tarballs.sh  # py310 (optionally add specific version of Python)

.\scripts\make_windows_zip.ps1 # py310 (optionally add specific version of Python)

pixi run -e publish publish-tarball-cache --itk-package-version v6.0b02 --build-dir-root /path/to/build/root

To see how to publish wheels see this section:

pixi run -e publish publish-wheels --dist-directory /path/to/dist/

ITKPythonPackage currently supports building wheels for the following platforms and architectures:

• Windows 10/11 x86_64 platforms
• macOS arm64 (Apple Silicon)
• macOS x86_64 (Intel)
• Linux glibc 2.17+ (e.g. Ubuntu 20.04+) x86_64
• Linux glibc 2.28+ (e.g. Ubuntu 20.04+) aarch64 (ARMv8)

Python 3.10+ is required.

ITKRemoteModuleBuildTestPackageAction CI workflows support Python 3.10–3.11 on GitHub-hosted runners for:

• Ubuntu x86_64
• Ubuntu aarch64 (ARM)
• macOS arm64 (Apple Silicon)
• Windows x86_64

Please open an issue in the ITKPythonPackage issue tracker for discussion, and consider contributing either time or funding to support development. The ITK open source ecosystem is driven through contributions from its community members.

The Insight Toolkit consists of several baseline module groups for image analysis including filtering, I/O, registration, segmentation, and more. Community members can extend ITK by developing an ITK "external" module which stands alone in a separate repository and its independently built and tested. An ITK external module which meets community standards for documentation and maintenance may be included in the ITK build process as an ITK "remote" module to make it easier to retrieve and build.

Visit ITKModuleTemplate to get started creating a new ITK external module.

ITK uses SWIG to wrap C++ filters for use in Python. See Chapter 9 in the ITK Software Guide or visit ITKModuleTemplate to get started on writing .wrap files.

After you've added wrappings for your external module C++ filters you may build and distribute Python packages automatically with ITKRemoteModuleBuildTestPackageAction or manually with ITKPythonPackage scripts.

In order to build an ITK external module you must have first built ITK for the same target platform. However, building ITK modules and wrapping them for Python can take a very long time! To avoid having to rebuild ITK before building every individual external module, artifacts from the ITK build process (headers, source files, wrapper outputs, and more) are packaged and cached as ITKPythonBuilds releases.

In order to build Python wheels for an ITK external module, ITKPythonPackage scripts first fetch the appropriate ITK Python build artifacts along with other necessary tools. Then, the module can be built, packaged, and distributed on PyPI.

Start by consulting the ITKPythonPackage ReadTheDocs documentation and the ITKPythonPackage issue tracker for discussion related to your specific issue.

If you aren't able to find an answer for your specific case, please start a discussion the ITK Discourse forum for help.

• Free software: Apache Software license
• Documentation: http://itkpythonpackage.readthedocs.org
• Source code: https://github.com/InsightSoftwareConsortium/ITKPythonPackage