Getting Started#

Prerequisites#

Before installing Phenotypic, ensure you have the following prerequisites:

Python 3.10 or higher
pip (Python package installer)
uv (recommended; see https://docs.astral.sh/uv/)

Installation Methods#

From PyPi#

Using uv (recommended)#

uv add phenotypic

Using pip#

pip install phenotypic

From Source#

To install from source:

git clone https://github.com/exfab/PhenoTypic.git
cd PhenoTypic && uv sync

Optional Extras#

PhenoTypic provides optional extras for different use cases:

[gui] — Browser-based GUI hub: Plotly dashboards, Dash apps, and Jupyter integration. Does not include napari.
[napari] — The interactive napari desktop viewers (pulls napari + PyQt6). Required for image.rgb.napari() and related viewer methods, and the point picker.
[torch] — PyTorch + SAM2 for Sam2 (Linux/macOS only).

# Browser GUI hub (Plotly, Dash, Jupyter)
uv add "phenotypic[gui]"

# napari desktop viewers
uv add "phenotypic[napari]"

# SAM2 GPU detector (Linux/macOS)
uv add "phenotypic[torch]"

micro_sam (used by MicroSamDetector) is only published on conda-forge and is not included in any PhenoTypic extra. See Deep Learning Detectors below for a self-service recipe that combines PhenoTypic and micro_sam in a single pixi environment.

Optional libvips acceleration#

On macOS and Windows, the [gui] extra installs the official pyvips binary distribution, including a self-contained native libvips. No separate system installation or loader-path configuration is needed for the normal GUI installation.

Linux and HPC installations use the smaller pyvips binding. Provide native libvips through the operating system or a site environment module when the faster DZI path is wanted:

# Debian or Ubuntu
sudo apt install libvips-dev --no-install-recommends

On a cluster, load the site’s libvips module before launching the GUI when one is available.

Verify that the native library is visible from the same shell that will launch PhenoTypic:

uv run python -c "import pyvips; print('pyvips', pyvips.__version__, 'libvips', '.'.join(str(pyvips.version(i)) for i in range(3)))"

The bundled build includes common image loaders but omits optional PDF and OpenSlide support. Users who intentionally prefer a fuller Homebrew libvips can install it with brew install vips. If that system install is present but the dynamic loader cannot find libvips.42.dylib, set the fallback library path before running either the verification command or the GUI:

export DYLD_FALLBACK_LIBRARY_PATH="$(brew --prefix vips)/lib${DYLD_FALLBACK_LIBRARY_PATH:+:$DYLD_FALLBACK_LIBRARY_PATH}"

If pyvips cannot load its native library, PhenoTypic automatically uses its Pillow implementation. All viewer features remain available, although large DZI pyramids can take longer to prepare and require more memory.

Deep Learning Detectors#

PhenoTypic ships several deep-learning colony detectors — Sam2, Sam3, DinoSam2Detector, Insid3Detector, FssDinoDetector, and the conda-only MicroSamDetector. This section covers installing the detector packages and pre-downloading their model weights. For detector usage, parameter tuning, device selection, and SLURM staging, see the GPU Detection Setup how-to guide.

Installing the detector packages#

The PyPI-published detectors are grouped into optional extras:

Extra	Detectors	Notes
`[torch]`	`Sam2`	PyTorch + `sam2` from PyPI. Linux/macOS only — no Windows wheels (use WSL2).
`[foundation]`	`Sam3`, `DinoSam2Detector`, `Insid3Detector`, `FssDinoDetector`	`transformers` (>=5.2.0) + `huggingface_hub` (pulls `torch`).
`[gpu]`	all of the above	Umbrella extra — every GPU detector at once (recommended for a dev env).

# SAM2 only
uv add "phenotypic[torch]"

# SAM3 + DINO-based foundation detectors
uv add "phenotypic[foundation]"

# Everything, inside a uv-managed checkout
uv sync --extra gpu

MicroSamDetector depends on micro_sam, which is published only on conda-forge and so is not part of any PhenoTypic extra. Manage the combined stack yourself — for example with pixi, which resolves conda-forge and PyPI in one lockfile, or with conda:

pip install phenotypic                   # or phenotypic[torch] on non-Windows
conda install -c conda-forge micro_sam   # adds MicroSamDetector

Model weights and licenses#

PhenoTypic does not redistribute model weights — each is downloaded from its upstream source under that model’s license. Most weights are ungated (SAM2, DINOv2), but SAM3 and DINOv3 weights are gated and need a one-time license handshake on the Hugging Face Hub:

Create a Hugging Face account.
Accept the gate on the model page (this is the license acceptance): SAM3 → https://huggingface.co/facebook/sam3, DINOv3 → https://huggingface.co/facebook/dinov3-vitb16-pretrain-lvd1689m.
Authenticate locally once: uv run hf auth login (or export HF_TOKEN).

Downloading and caching checkpoints#

Every detector downloads its weights automatically on first use, but you can pre-download them with the phenotypic.detect.nn CLI — essential on SLURM clusters whose compute nodes have no internet access:

# SAM2 (default tiny; --all for every size)
uv run python -m phenotypic.detect.nn download --model-type sam2 --model-size tiny

# micro-sam
uv run python -m phenotypic.detect.nn download --model-type microsam --model-name vit_b_lm

# Gated foundation weights — --accept-license acknowledges the model license
uv run python -m phenotypic.detect.nn download --model-type sam3 --accept-license
uv run python -m phenotypic.detect.nn download --model-type dinov3 --dino-size base --accept-license

# Ungated DINOv2 (no token needed)
uv run python -m phenotypic.detect.nn download --model-type dinov2 --dino-size base

# Inspect or clear the cache
uv run python -m phenotypic.detect.nn list
uv run python -m phenotypic.detect.nn clear --model-type sam2

Cache locations are controlled by environment variables — point them at shared storage so SLURM compute nodes can read pre-staged weights:

Variable	Controls
`TORCH_HOME`	SAM2 checkpoint cache (default `~/.cache/torch/hub/checkpoints/`).
`MICROSAM_CACHEDIR`	micro-sam checkpoint cache.
`HF_HOME` / `HF_HUB_CACHE`	Hugging Face cache for SAM3 + DINO weights.
`HF_HUB_OFFLINE=1` / `TRANSFORMERS_OFFLINE=1`	Force load-from-cache on offline compute nodes.
`HF_TOKEN` / `HUGGING_FACE_HUB_TOKEN`	Auth for gated downloads (alternative to `hf auth login`).
`PHENOTYPIC_ACCEPT_MODEL_LICENSE`	Non-interactive license acknowledgement for batch/SLURM jobs (e.g. `sam3,dinov3`).

Note

On a cluster, accept the gates and pre-stage weights on the login node (which has internet), then run the compute job offline with the same HF_HOME plus HF_HUB_OFFLINE=1 and PHENOTYPIC_ACCEPT_MODEL_LICENSE. Acceptance never happens silently inside a batch job. See the GPU Detection Setup guide for the full SLURM staging workflow.

Development Installation#

For development of new modules, sync with the dev (and optionally docs) dependency groups:

git clone https://github.com/exfab/PhenoTypic.git
cd PhenoTypic
uv sync --group dev --group docs

Verification#

To verify the installation, run:

import phenotypic
print(phenotypic.__version__)

Launching the GUI#

The unified GUI hub bundles the pipeline builder, results viewer, and run console under one URL. Start it with the phenotypic-gui console script:

uv run phenotypic-gui --root ./images --port 8050

--root freezes the sandbox the GUI’s file browser is allowed to see (defaults to the current working directory). --host 127.0.0.1 (the default) keeps the server loopback-only — pair with SSH port forwarding for remote workstations:

ssh -L 8050:localhost:8050 user@cluster

Then open http://localhost:8050/ in your browser. If you launch the GUI from inside a Slurm allocation (srun/salloc), the server binds to the compute node rather than the login node, and the single-hop tunnel above will return connect failed: Connection refused. See Running the GUI on a Slurm compute node in the GUI hub guide for the two-hop tunnel pattern. That guide also covers the file browser, pipeline builder, run console, and results viewer.

For Open OnDemand-style proxies, pass the browser path as a prefix, not the full URL:

uv run phenotypic-gui --root /rhome/ejaco020 --host 0.0.0.0 --port 30099 --url-prefix /node/hz01/30099/

Then open the full proxy URL, for example https://ondemand.hpcc.ucr.edu/node/hz01/30099/.