Installation

Python environment and Python version

Either way you choose below, first create and activate a Python 3.12 environment, for example:

conda create -n cellcoloc python=3.12 -y
conda activate cellcoloc

Installation on Windows with GPU support

On Windows and in case you have a CUDA-ready GPU, we recommend installing PyTorch prior to CellColoc in order to prevent the installation of the CPU-only PyTorch version for Cellpose. Thus, in case you want to use Cellpose with GPU acceleration on your Windows PC, please follow these steps instead of the standard installation above:

  1. If not already done, install or update the NVIDIA drivers. For the standard PyTorch wheels from the PyTorch website, a separate CUDA Toolkit or cuDNN installation is often not required, because the wheel already bundles the needed CUDA runtime components. If you use a custom CUDA or PyTorch setup, however, those additional installations may still be relevant.

  2. Find out your CUDA version by running nvidia-smi in the terminal.

  3. Visit the PyTorch website and copy the correct command for your system. Important: Do not execute the PyTorch installation command yet! We first need to create a virtual environment for CellColoc and then install PyTorch in that environment!

  4. Create a virtual environment for CellColoc using Python 3.12, e.g.,

    conda create -n cellcoloc python=3.12 -y
conda activate cellcoloc

  5. In that environment, paste the PyTorch installation command you found in step 3. For example, for a system with CUDA 13.0, you would use:

    pip install torch torchvision --index-url https://download.pytorch.org/whl/cu130

  6. Verify that PyTorch can access your GPU:

    python -c "import torch; print(torch.cuda.is_available())"

Now you can follow one of the installation methods described below.

Python version

We have tested CellColoc with Python 3.12. Newer versions may work but are not guaranteed to be compatible. Older Python versions are not supported, as CellColoc relies on OMIO for reading microscopy data, and OMIO requires Python 3.12 or newer.

PyPI

The standard installation is:

pip install cellcoloc

Interactive use

If you want to use CellColoc together with VS Code’s interactive window or a notebook-like workflow, install the interactive extra:

pip install "cellcoloc[interactive]"

Cellpose 3

CellColoc is designed to work with both older Cellpose 3 installations and newer Cellpose 4 installations.

If you specifically want the tested Cellpose 3 variant, install:

pip install "cellcoloc[cellpose3]"

Alternatively, you can install CellColoc first and then pin Cellpose manually:

pip install cellcoloc
pip install "cellpose==3.1.1.2"

Development install

For local development from a clone of the repository:

git clone https://github.com/FabrizioMusacchio/CellColoc.git
cd CellColoc
pip install -e .

For interactive development:

pip install -e ".[interactive]"

Updating CellColoc

To update an existing installation, run:

pip install --upgrade cellcoloc

If you are using the interactive extra, run:

pip install --upgrade "cellcoloc[interactive]"

If you are using the development install, run, after pulling the latest changes from the repository:

pip install --upgrade -e .

or, for interactive development:

pip install --upgrade -e ".[interactive]"

Removing the CellColoc environment

In case you want to remove the CellColoc conda environment you have created in the steps above, e.g., for a fresh reinstallation, simply execute the following command after deactivating the environment:

conda env remove -n cellcoloc

User-scripts

Please visit CellColoc’s GitHub repository for the latest user-scripts. The repository contains a user_scripts/ directory with example scripts for 2D and 3D datasets, including single-channel and three-channel analyses. We discuss them in detail in the Usage section of the documentation.

Example datasets

In order to run the example user-scripts, you will need to download the example datasets. Please refer to the Example data set section and follow the download instructions there.

Dependencies

The core package currently depends on:

  • cellpose

  • omio-microscopy

  • matplotlib

  • pandas

  • openpyxl

  • scikit-image

  • appdirs

The optional interactive extra additionally provides:

  • ipykernel