Skip to content

Development and manual installation

This guide covers manual installation using conda, pip, and uv for users who prefer a command-line setup or are developing SenoQuant.

Note: For most users, the installers are recommended because they simplify setup and select the supported runtime for the host platform.

Automated development setup

The repository provides setup scripts under scripts/development/. Each script creates or updates the senoquant-dev conda environment with Python 3.11, OpenJDK, JPype, scyjava, napari, the test dependencies, and an editable SenoQuant installation.

Prerequisites:

  • A local SenoQuant repository checkout.
  • Miniforge, Miniconda, or Anaconda with conda available in the terminal.

Run the script for your operating system from the repository root.

Windows (PowerShell):

.\scripts\development\setup_windows.ps1

macOS:

bash scripts/development/setup_macos.sh

Linux:

bash scripts/development/setup_linux.sh

After setup:

conda activate senoquant-dev
python -m pytest -q
napari --with senoquant

The scripts are safe to rerun: they update an existing environment instead of replacing it. To use another environment name, pass it as the first argument on macOS/Linux or use -EnvironmentName on Windows:

bash scripts/development/setup_linux.sh my-senoquant-env

.\scripts\development\setup_windows.ps1 -EnvironmentName my-senoquant-env

On a Windows ARM64 PC, the Windows script creates a win-64 conda environment. Python and native dependencies then run through Windows 11 x64 emulation, matching the supported installer configuration. Windows 11 24H2 or later is required.

The following sections describe the equivalent manual process.

Create an environment

In your terminal (Command Prompt/PowerShell on Windows, Terminal on macOS/Linux), create and activate a new conda environment with Python 3.11.

conda create -n senoquant python=3.11
conda activate senoquant

You should see (senoquant) at the beginning of your terminal prompt, indicating that the environment is active.

Install uv and napari

We strongly recommend using uv instead of pip because standard pip often has difficulty solving complex dependencies. uv is also much faster.

pip install uv
uv pip install pip-system-certs
uv pip install "napari[all]"

Note: pip-system-certs enables Python to use your system's certificate store for SSL verification. This helps avoid certificate errors when downloading packages or models, especially on corporate networks or systems with custom certificate authorities. The bundled installers also run uv with --system-certs and clear SSL_CERT_FILE / SSL_CERT_DIR inside the micromamba child process so package downloads use the OS trust store during post-install setup.

Alternatively, using standard pip:

pip install "napari[all]"

Install SenoQuant

uv pip install senoquant

Alternatively, using standard pip (not recommended. This might be fine for napari, but often fails for SenoQuant):

pip install senoquant

Warning (Windows): Installing via pip/uv may not pull a GPU-enabled PyTorch build on Windows. If you need GPU acceleration, use the Windows installer instead. Or, troubleshoot PyTorch installation manually by following the official PyTorch instructions.

BioFormats (Java) setup

SenoQuant uses format-specific BioIO readers (for example bioio-czi, bioio-ome-tiff, and bioio-ome-zarr) for fast data loading and uses BioFormats via bioio-bioformats for metadata extraction when available. BioFormats requires Java. The bundled installers install OpenJDK, JPype, and scyjava into their dedicated environments; manual conda installs should include openjdk, jpype1, and scyjava.

If you get a JVMNotFoundException when reading images, set JAVA_HOME manually:

  • macOS/Linux: export JAVA_HOME=$CONDA_PREFIX
  • Windows: set JAVA_HOME=%CONDA_PREFIX%\Library

Optional dependencies

  • uv pip install senoquant[all] for full stack.

Launch

Start napari from your terminal:

napari --with senoquant

The first launch of napari and the SenoQuant plugin will be slower as napari initializes and SenoQuant downloads model files (a few GBs) from Hugging Face. Subsequent launches will be faster as models are cached locally.

Make sure the terminal remains open while using napari to keep it running. The terminal also displays useful info/warning/error messages.

Development installation

For development work without the setup scripts, install SenoQuant and the test dependencies from the repository in editable mode:

pip install uv
uv pip install "napari[all]" -r requirements-test.txt -e .

This allows you to make changes to the code and see them reflected immediately without reinstalling.