Installation

The imfusion module is distributed in the form of Python wheels (.whl files) either hosted on our package index or provided directly by us:

Package Index: All releases of the ImFusion Python SDK (imfusion-sdk packages) are hosted on pypi.imfusion.com/simple. Each release depends on a stable version of the ImFusion C++ SDK, which is also hosted as Python packages (libimfusion) on the same index. See Installation from package index for more information.
Custom wheels: If you are contracting us for a R&D / consulting project, you might receive wheel files (.whl) from us for custom builds as part of the project. See Installation from wheel files for further information.

Warning

The imfusion module requires Python 3.10 or higher. We recommend using official Python interpreters from python.org. Installers obtained with uv are also compatible. Currently, this package is not tested with interpreters from Anaconda, so use them at your own risk.

Installation from package index

The imfusion package can be installed directly using a package manager, e.g. pip, from our package index pypi.imfusion.com/simple:

pip install imfusion-sdk  --extra-index-url https://pypi.imfusion.com/simple

We offer many additional modules as separate plugin packages, e.g. imfusion-sdk-machinelearning, imfusion-sdk-dicom, etc. You can either install them explicitly by name, or specify them as optional dependencies, as shown below.

pip install imfusion-sdk[machinelearning, dicom, ...] --extra-index-url https://pypi.imfusion.com/simple

Note

While pip install can be run with the base interpreter, we highly recommend creating a virtual environment to avoid potential conflicts with other packages. See venv documentation and virtualenv documentation for more information on virtual environments in Python.

Note

If your Python interpreter does not come with pip (it normally does), please consult the pip installation guide from PyPA.

The imfusion-sdk package and all plugins that are part of the base package covered by all our SDK subscription plans (Free, Starter, Professional) can be installed through imfusion-sdk[webshop-base]. Our modality specific plugins like imfusion.vision or imfusion.computed_tomography are also available, e.g. via imfusion-sdk[vision], however you will need to purchase an additional license. These plugins are only usable with the “Starter” and “Professional” plan licenses.

We also provide optional dependencies for the following webshop bundles: - imfusion-sdk[webshop-ultrasound] - imfusion-sdk[webshop-vision] - imfusion-sdk[webshop-xray-ct] - imfusion-sdk[webshop-navigation] - imfusion-sdk[webshop-robotics] - imfusion-sdk[webshop-spine]

Besides the imfusion-sdk packages, these bundles also contain libimfusion packages which represent plugins for the ImFusion C++ SDK. While you cannot interact with them directly via a Python API, they offer additional functionality accessible through the generic algorithm API, e.g. imfusion.execute_algorithm(). The libimfusion packages can also be downloaded individually.

To get a full list of all provided optional dependencies you can run the following command after installing imfusion-sdk:

python -c "from importlib import metadata;print(*metadata.metadata('imfusion-sdk').get_all('Provides-Extra'), sep='\n')"

Installation from wheel files

If you receive .whl files from us directly for a custom build, the installation process is analogous to what is described in Installation from package index. The only difference is that your package manager must be configured to resolve dependencies locally:

For `pip (and uv pip), the -f <folder-with-wheels> option specifies the directory where dependencies can be found. Additionally, you need to substitute imfusion-sdk with your local wheel imfusion_sdk-<version>-<python>-<abi>-<platform>.whl (on macOS and Linux you can simply use imfusion_sdk-*.whl). As an example, if you want to install imfusion-sdk with the base modules + ultrasound from provided wheel files your command would look like this:

cd <wheels-folder>
pip install -f . ./imfusion_sdk-<version>-<python>-<abi>-<platform>.whl[base, ultrasound]

License Activation

Before you can import imfusion, you must activate it once. You can obtain a license key from our webshop. If you intend to use :mod`imfusion` strictly for non-commercial applications and don’t need any modality-specific modules you can get a license key for free

The activation can be done either through the ImFusionSuite (a prompt will appear the first time you start it) or through the Python CLI:

Linux and macOS:

IMFUSION_LICENSE_KEY=<your-license-key> python3 -c "import imfusion"

Windows CMD:

set IMFUSION_LICENSE_KEY=<your-license-key> && python.exe -c "import imfusion"

A successful activation will exit without an error, while an unsuccessful one will print details of why the activation failed. The activation requires an active internet connection. A proxy can be set with the HTTPS_PROXY environment variable. The IMFUSION_LICENSE_KEY only needs to be set once for the initial activation.

Uninstalling

To easily uninstall all imfusion packages from your venv you can simply run imfusion uninstall -y after activating the respective venv.

With the ImFusion Suite

The ImFusion Suite provides an embedded Python interpreter and console.

On first start, the ImFusionSuite will try to automatically detect an installed Python environment. If this doesn’t work or if you want to use, e.g., a different Python version, you can configure different versions in Settings -> Python -> Active Environment. Click on the ‘+’ button to add the path to the Python interpreter you want to use. If the interpreter is located inside a virtual environment, the ImFusion Suite interpreter will use the corresponding environment. Additionally, if you start the Suite from an active Python virtual environment, the Suite’s interpreter will also use that environment, irrespective of what is stored in the Settings.

Warning

The Python integration in the ImFusion Suite works only if you have a shared library for the interpreter you want to use on your system. On Windows / macOS, it is included in the installers provided on python.org in the form of a .dll / .dylib (e.g., libpython310.dll or libpython3.10.dylib). If you are on Ubuntu and you install your Python interpreter from the deadsnakes PPA, you must also install the pythonX.YY-dev package to obtain the shared library. If loading the library fails, you won’t see the Python console, and an error will be printed in the log window.

Note

The interpreter in the ImFusion Suite currently only supports virtual environments created through venv, virtualenv or uv. Anaconda is not supported at the moment.

If the environment is correctly configured, the interpreter is automatically initialised when the ImFusionPython plugin is loaded. Otherwise, an error is displayed in the log window. Depending on the size of your log window the error might go out of the visible scope and you have to scroll up to see it.

Note

If you cannot see a Python console in the bottom right of the window, go to Settings -> Python and select the desired console.