Installation

You can try DeLTA out without installing anything on Google Colab.

You can also install DeLTA on your computer or your cluster easily with pip or pixi, as described on this page.

Note

Previous versions of DeLTA also offered installation via conda, but we have been dropping support for it, since pip installation is now reliable.

Hardware requirements

DeLTA runs much faster on a GPU. To do so you will need an nvidia gpu with a cuda compute capability of 3.5 or higher and an up-to-date gpu driver. If no compatible GPU/driver is found on the system, DeLTA will run on the CPU, but it will be slower. Computing clusters and cloud computing platforms are also an alternative that has been working well for us.

Prerequisites

If you want to use DeLTA on Windows, we recommend installing it inside WSL (Windows Subsystem for Linux).

WSL can be seen as a Linux emulator running inside Windows. If you already have it installed, you can already continue with the Linux instructions. Otherwise, install it, and then follow the Linux instructions.

Installing WSL

To activate WSL on Windows, first ensure that Windows Update is up to date, and if you have a GPU make sure you are using the latest drivers.

Then, using the “Turn Windows features on or off” tool, turn on the Virtual Machine Platform and the Windows Subsystem for Linux features. You may now check again for Windows updates.

Using the Microsoft app store, download the Windows Terminal to make the terminal use more agreeable.

You next need to install a Linux distribution. Type wsl --list --online in the Windows terminal to see a list of options. Debian is a good choice, to install it type wsl --install -d Debian. Setup a username and a password, and you now have a fully functional Linux distribution running inside Windows. Type wsl --list --verbose in any Windows terminal, and make sure that the version number is 2, otherwise you will have to either update wsl with wsl --update or by following these steps.

You can start upgrading Debian by typing the following commands in the Linux terminal:

$ sudo apt update
$ sudo apt upgrade

Note

The dollar sign is not a part of the command, it just represents the invite prompt.

You are now ready to continue with the Linux section of this guide.

You can from now on follow the Linux instructions, starting with this tab.

To save annotated movies, DeLTA requires ffmpeg installed. The easiest way is to use your system’s package manager (e.g sudo apt install ffmpeg on Debian/Ubuntu). See python-ffmpeg’s page for more information. You might also have to install the development versions of libxslt and libxml. (e.g. sudo apt install libxml2-dev libxslt-dev on Debian / Ubuntu).

If you want to use your GPU, make sure you have the latest proprietary Nvidia drivers installed.

Note that pixi will install all of this by itself if you choose this installation method.

Even though we did not test ourselves the installation of DeLTA on Mac OS, we have been told that it works well.

Installation

Then use pipx! It will install DeLTA transparently, in a dedicated environment and you can then use the command delta as any other program.

Simply run the following command to install DeLTA:

$ pipx install delta-microscopy[jax-cpu]

Note

The brackets behind the package name allow to select the deep learning backend that you prefer: you can choose jax, torch or tf and for each of these options you can choose cpu or gpu depending on your hardware.

You can now use the delta command, and import delta in a Python script.

Attention

Note that the pip package name is delta-microscopy but the python package to import is just delta.

Then use pip, uv or pixi!

If you want that, you probably already know how to create a Python environment. In which case, you can install DeLTA into it with:

$ pip install delta-microscopy[jax-gpu]

You can now use import delta in Python scripts.

Note

The brackets behind the package name allow to select the deep learning backend that you prefer: you can choose jax, torch or tf and for each of these options you can choose cpu or gpu depending on your hardware.

Note

We can’t resist mentioning pixi because it works very well! To create and activate a project using DeLTA, this is how you could do it with pixi:

$ mkdir my_library
$ cd my_library
$ pixi init
$ pixi add python=3.14
$ pixi add --pypi delta-microscopy[jax-gpu]
$ pixi shell

Attention

Note that the pip package name is delta-microscopy but the python package to import is just delta.

Then use pixi (you can also do it with pip or uv, but we find pixi more convenient)!

First clone and enter our git repository:

$ git clone https://gitlab.com/delta-microscopy/DeLTA
$ cd delta

You can now specify your preferred deep learning library backend, and specify whether you would like to install the CPU or GPU version. To install the dependencies for pytorch and run it on GPU, run the following command, inside your cloned DeLTA directory:

$ pixi shell -e torch-gpu

Note

The argument after -e allows to select the deep learning backend that you prefer: you can choose jax, torch or tf and for each of these options you can choose cpu or gpu depending on your hardware.

That’s it, DeLTA is installed and you can change its code!

Note

This version is installed from sources and may therefore differ significantly from the stable versions available on PyPI.

Note

You don’t need to create a special environment with pixi, it takes care of that on its own.

To exit simply:

$ exit

More information on pixi.

Check installation

In all cases, you should now have a command named delta available from your terminal, and also be able to import delta within the Python environment.

To check that your backend is able to detect the GPU, please run the following in the python interpreter:

>>> import torch
>>> torch.cuda.is_available()

Should return True

>>> import tensorflow as tf
>>> tf.config.list_physical_devices()

Your GPU should appear in the list.

>>> import jax
>>> jax.devices(backend="gpu")

Your GPU should appear in the list.

Troubleshooting

cuDNN (or other libraries) not loading

We have run into OOM errors or some GPU-related libraries failing to load or initialize on laptops. See the “Limiting GPU memory growth” section on this tensorflow help page. Setting the memory_growth_limit parameter in the JSON config file to a set value in MB (eg 1024, 2048…) should solve the issue.

OOM - Out of memory (GPU)

On GPU, you might run into memory problems. This is both linked to the batch size and the size of the images. The batch size is straightforward to change, lower the value at the beginning of the training scripts. Note that lower batch sizes may mean slower training convergence or lower performance overall.

The other solution would be to use a smaller image target size. However if the original training images and masks are for example 512×512, downsizing them to 256×256 will reduce the memory footprint, but it might cause some borders between cells in the binary masks to disappear. Instead, training images should be resized upstream of DeLTA to make sure that your training set does feature cell-to-cell borders in the segmentation masks.

Another reason why this may happen is that the pipeline is trying to process too many samples at once. Try lowering pipeline_seg_batch, pipeline_track_batch, and pipeline_chunk_size in your config.