Installation¶

Prerequisites¶

The prerequisites for TIAToolbox installation are OpenSlide binaries and OpenJPEG version 2.3.0 or above. Please follow the instructions below to install the prerequisite software according to your platform.

Linux (Ubuntu)¶

On Linux, the prerequisite software can be installed using the following command:

$ apt-get -y install libopenjp2-7-dev libopenjp2-tools sqlite3 libsqlite3-0

The same command is used when working on the Colab or Kaggle platforms. When working on Google Colab, the following packages should be removed before installing TIAToolbox, as they conflict and may produce an error message:

$ pip uninstall -y datascience albumentations

Windows (10+)¶

On Windows, OpenJPEG and SQLite can be installed using the following conda command:

C:\> conda install -c conda-forge openjpeg sqlite

macOS¶

On macOS, there are two popular package managers, homebrew and macports.

Homebrew¶

$ brew install openjpeg sqlite

MacPorts¶

$ port install openjpeg sqlite

Installing Stable Release¶

Please note that TIAToolbox is tested for Python versions 3.11, 3.12, 3.13 and 3.14. For the full range of supported Python versions, please refer to the package metadata (for example, the python_requires setting in setup.py or pyproject.toml)

Upgrade¶

To upgrade an existing version of TIAToolbox to the latest stable release, run this command in your terminal:

$ pip install --ignore-installed --upgrade tiatoolbox

Without Dependencies¶

If you already have a Python environment set up with all the prerequisite software and dependencies installed and you would like to keep the existing versions of these dependencies, run this command in your terminal:

$ pip install --no-deps tiatoolbox

If you don’t have pip installed, this Python installation guide can guide you through the process.

Alternative Methods¶

Using Anaconda¶

After installing Anaconda (or miniconda / mamba), you can install TIAToolbox using the following command:

$ conda install -c conda-forge tiatoolbox

or

$ mamba install tiatoolbox

An alternate way to install using conda on Windows could be to install it in WSL2 with CUDA support. Depending on your hardware and workload, WSL2 may offer improved performance for some Python workflows, and therefore we recommend this option.

Using uv¶

To install using uv, a fast Python package and project manager, written in Rust.

$ pip install uv
$ uv pip install tiatoolbox

From Sources¶

The sources for TIAToolbox can be downloaded from the GitHub repo.

You can either clone the public repository:

$ git clone https://github.com/TissueImageAnalytics/tiatoolbox.git

Or download the tarball:

$ curl -OJL https://github.com/TissueImageAnalytics/tiatoolbox/tarball/master

Once you have a copy of the source, you can install it with:

$ python setup.py install

Using Docker¶

To run TIAToolbox in an isolated environment, use our Docker image. We host different Dockerfiles in our GitHub repository tiatoolbox-docker. Please report any issues related to the Docker image in the repository tiatoolbox-docker.

After installing Docker (or Docker Desktop), you can use our TIAToolbox image in three different ways.

Use the Pre-Built Docker Image¶

TIAToolbox provides pre-built Docker containers which can be downloaded using the instructions below:

  1. Pull the Image From GitHub Container Registry:

$ docker pull ghcr.io/tissueimageanalytics/tiatoolbox:latest

  1. Use the Pre-Built Docker Image as a Base Image in a Dockerfile:

FROM ghcr.io/tissueimageanalytics/tiatoolbox:latest

Build the Image Locally¶

  1. Navigate to the Dockerfile that you want to use, based on the Python version and Operating System that you prefer.

  2. Build the Docker image:

$ docker build -t <IMAGE_NAME> .

  1. Check that the image has been created:

$ docker images

  1. Deploy the image as a Docker container:

$ docker run -it --rm --name <CONTAINER_NAME> <IMAGE_NAME>

  1. Connect to the running container:

$ docker exec -it <CONTAINER_NAME> bash

To add your own script and run it through the Docker container, first copy your script into the Docker environment and then execute it:

COPY /path/to/<script>.py .
CMD ["python3", "<script>.py"]