Installation#

The developer version of InVesalius runs on Windows, macOS, and Linux operating systems. On this page, instructions for installing and running InVesalius on these systems can be found.

Windows#

These instructions are tested on Windows 10 64-bit. The packages required by InVesalius can be installed either through a Python system installation, the Anaconda package manager, or using uv. In all cases, the following prerequisites apply:

Prerequisites#

Visual Studio (We are using the 2019 community edition).

It’s possible to install using chocolatey:

 choco install -y visualstudio2019buildtools
 choco install -y visualstudio2019-workload-vctools

Download InVesalius source code.

git clone --recurse-submodules https://github.com/invesalius/invesalius3

Installation Options#

Option 1: Using `uv` (Recommended)#

uv is a modern Python package manager that ensures better dependency management. Follow these steps:

Install uv on Windows using:
```
winget install --id=astral-sh.uv  -e
```
Navigate to the cloned InVesalius directory:
```
cd invesalius3
```
Install dependencies and compile Cython extensions automatically:
```
uv sync
```
Run InVesalius:
```
uv run app.py
```

Tip: To install additional dependencies, use:

uv add <dependency-name>

Option 2: Python System Installation#

Download and install Python 3.8 from the Python website.
Create a virtual environment using
```
python3 -m venv .venv
```
Activate the virtual environment using
```
.venv\bin\activate
```
Install InVesalius main dependencies and compile cython extensions using pip:
```
pip install -e .
```
If you are going to use the neuronavigation features, install the wrappers for tracking devices:
```
pip install pyclaron polhemusFT polhemus pypolaris pypolarisP4
```

Optional: To enable real-time tractography computation, install Trekker:

pip install https://github.com/dmritrekker/trekker/raw/master/binaries/Trekker-0.9-cp38-cp38-win_amd64.whl

Option 3: Anaconda Installation#

Install Anaconda, preferably the 64-bit version.
In the Anaconda Powershell, navigate to the cloned InVesalius source code folder:
```
cd C:\Users\%USERNAME%\repository\invesalius3\
```

Install the required packages:

conda env create -f environment.yml --name invesalius

Activate the virtual environment:
```
conda activate invesalius
```
Compiling InVesalius:

Some algorithms of InVesalius are written in Cython for performance. These need to be compiled manually:
```
python setup.py build_ext --inplace
```

Running InVesalius#

Inside the InVesalius source code directory, run:

python app.py

Warning: If using Anaconda or pip , always activate the environment using .venv\bin\activate before running the command.

If using uv, simply run:

uv run app.py

MacOS#

This guide is based on High Sierra.

Prerequisites#

The first step is the installation of homebrew. Access the homebrew site to know how to install it.

We recommend installing Python 3 from brew, and also installing OpenMP (we use it):

brew install python3 libomp

If you are working with an Apple Silicon Mac, you also have to install hdf5:

brew install hdf5

Clone InVesalius 3 using git:

git clone --recurse-submodules https://github.com/invesalius/invesalius3

Installation#

To run the following commands, ensure your shell is inside the InVesalius folder:

cd invesalius3

Preferred Installation Method (Using `uv`)#

We have transitioned to using uv for dependency management and scikit-build-core with CMake for compiling Cython modules.

Install uv:
```
brew install uv
```
Sync dependencies:

a) First-time installation (or when compiling Cython extensions):
```
OpenMP_ROOT=$(brew --prefix)/opt/libomp uv sync
```
b) For subsequent dependency synchronization (when Cython compilation is not needed):
```
uv sync
```

Alternative Installation Method (Legacy `pip` Workflow)#

Install dependencies using:

pip3 install -r requirements.txt

Compiling InVesalius (Legacy)#

If you are using a Mac with Apple Silicon, export the following environment variables before compiling:

export CFLAGS="-I/opt/homebrew/opt/libomp/include"
export CPPFLAGS="-I/opt/homebrew/opt/libomp/include"
export LDFLAGS="-L/opt/homebrew/opt/libomp/lib"

Compile the Cython packages used by InVesalius:

python3 setup.py build_ext --inplace

Running InVesalius#

Preferred Method (Using `uv`)#

After installation, launch InVesalius with:

uv run app.py

Alternative Method (Using Python Directly)#

python3 app.py

If you encounter the following error:

This program needs access to the screen. Please run with a
Framework build of python, and only when you are logged in
on the main display of your Mac.

Run InVesalius using:

pythonw app.py

Linux#

Packages Debian and Ubuntu#

InVesalius is already packaged and is in the main repos from Debian and Ubuntu. Install it using this command:

sudo apt install invesalius

If you want the most updated packages, there is also a PPA to Ubuntu:

sudo add-apt-repository ppa:tfmoraes/invesalius
sudo apt-get update
sudo apt install invesalius

After the installation, InVesalius appears in your system menu. You can also run it from the command line:

invesalius3

Other Distros#

InVesalius is packaged as Flatpak. First, you need to add the Flathub repo:

flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo

Then install InVesalius:

flatpak install flathub br.gov.cti.invesalius

After the installation, InVesalius appears in your system menu. You can also run it from the command line:

flatpak run br.gov.cti.invesalius

Source Code#

Use this command to get InVesalius source code from GitHub:

git clone --recurse-submodules https://github.com/invesalius/invesalius3

Installing Dependencies#

Using PIP Packages (recommended)#

First, you have to install some system packages to compile wxPython and H5py:

Fedora (tested on Fedora 34)

sudo dnf -y install \
    gcc-c++ \
    python3-devel \
    freeglut-devel \
    gstreamer1-devel \
    gstreamer1-plugins-base-devel \
    gtk3-devel \
    libjpeg-turbo-devel \
    libnotify-devel \
    libpng-devel \
    libSM-devel \
    libtiff-devel \
    libXtst-devel \
    SDL-devel \
    webkit2gtk3-devel \
    which \
    hdf5-devel

Ubuntu (tested on Ubuntu 20.10 and 21.04)

sudo apt install -y \
    freeglut3 \
    freeglut3-dev \
    libgl1-mesa-dev \
    libglu1-mesa-dev \
    libgstreamer-plugins-base1.0-dev \
    libgtk-3-dev \
    libjpeg-dev \
    libnotify-dev \
    libsdl2-dev \
    libsm-dev \
    libtiff-dev \
    libwebkit2gtk-4.0-dev \
    libxtst-dev \
    python3-dev \
    libhdf5-dev \
    build-essential \
    python3-venv

Arch

sudo pacman -syu \
    wxgtk3 \
    glu \
    mesa \
    webkit2gtk

It’s recommended to create a virtualenv

using uv (Preferred Method):

# Go to InVesalius folder
cd invesalius3

# Create .venv environment
uv venv

# Install dependencies and build cython extensions
uv sync

Tip: To add extra dependencies to the project use:

uv add <dependency-name>

using pip:

# Go to InVesalius folder
cd invesalius3

# Create my_env environment
python3 -m venv .venv

# Activate it every time you want to run InVesalius
source my_env/bin/activate

#Install dependencies and build cython extensions
pip install -e .

Using System Packages#

Debian and Ubuntu (Tested in Ubuntu 20.04)#

sudo apt install python3-wxgtk4.0 python3-numpy python3-scipy python3-pil python3-matplotlib python3-skimage python3-nibabel python3-serial python3-psutil python3-vtk7 python3-vtkgdcm python3-gdcm cython3 python3-h5py python3-imageio python3-keras python3-pubsub

Ubuntu don’t have PlaidML in their repositories, so install it using pip:

pip3 install --user plaidml-keras

Fedora (Tested in Fedora 32)#

sudo dnf install gcc gcc-g++ python3-wxpython4 python3-numpy python3-scipy python3-matplotlib python3-scikit-image python3-nibabel python3-pyserial python3-psutil python3-vtk python3-gdcm python3-Cython python3-h5py python3-pypubsub

Unfortunately, Fedora doesn’t have python3-imageio package. But it’s possible to install it using pip:

pip3 install --user imageio

Fedora don’t have PlaidML in their repositories, so install it using pip:

pip3 install --user plaidml-keras

Arch Linux#

sudo pacman -S cython python-pip python-numpy python-scipy python-scikit-learn python-wxpython python-pyserial python-psutil python-h5py python-pypubsub python-mpi4py python-matplotlib vtk clinfo opencl-headers gdal glew hdf5 jsoncpp netcdf pdal pugixml proj

You have to install some packages from AUR, I’m using Pikaur to install them:

pikaur -S --noconfirm gdcm python-nibabel python-scikit-image python-imageio python-plaidml python-plaidml-keras

Running InVesalius#

To run InVesalius, enter the InVesalius folder and use one of the following commands:

If using uv, run this command:

uv run app.py

If using pip,run this command:

python3 app.py

You can pass a DICOM folder as a parameter to make InVesalius start with the DICOM loaded.

Using uv:

uv run app.py -i /dicom/folder

Using Python:

python3 app.py -i /dicom/folder

It’s possible to make InVesalius load a DICOM folder,
create a surface (mesh) with the given threshold, and export the surface to an STL file without loading any GUI:

Using uv:

uv run app.py --no-gui -i /media/thiago/Documentos/dcm/0051 -t 200,3033 -e /tmp/0051.stl

Using Python:

python3 app.py --no-gui -i /media/thiago/Documentos/dcm/0051 -t 200,3033 -e /tmp/0051.stl

Installation#

Windows#

Prerequisites#

Installation Options#

Option 1: Using uv (Recommended)#

Option 2: Python System Installation#

Option 3: Anaconda Installation#

Running InVesalius#

MacOS#

Prerequisites#

Installation#

Preferred Installation Method (Using uv)#

Alternative Installation Method (Legacy pip Workflow)#

Compiling InVesalius (Legacy)#

Running InVesalius#

Preferred Method (Using uv)#

Alternative Method (Using Python Directly)#

Linux#

Packages Debian and Ubuntu#

Other Distros#

Source Code#

Installing Dependencies#

Using PIP Packages (recommended)#

Using System Packages#

Debian and Ubuntu (Tested in Ubuntu 20.04)#

Fedora (Tested in Fedora 32)#

Arch Linux#

Running InVesalius#

This Page

Option 1: Using `uv` (Recommended)#

Preferred Installation Method (Using `uv`)#

Alternative Installation Method (Legacy `pip` Workflow)#

Preferred Method (Using `uv`)#