Skip to content

Installation

Annolid currently exposes two main commands after install:

  • annolid: launch the desktop GUI
  • annolid-run: run model and workflow plugins from the terminal

Annolid requires Python 3.10 or newer and supports Python 3.10 through 3.14 for the default GUI/core workflow. In practice, Python 3.11 or 3.12 remains the safest default for new shared lab environments.

One-line installer

For most users, start with the project installers:

  • macOS and Linux:
curl -sSL https://raw.githubusercontent.com/healthonrails/annolid/main/install.sh | bash
  • Windows PowerShell:
irm https://raw.githubusercontent.com/healthonrails/annolid/main/install.ps1 | iex

See One-Line Installer for flags, extras, CPU/GPU choices, and non-interactive installs.

The one-line installers also validate ONNX Runtime provider selection. On Linux and Windows, onnxruntime-gpu is installed when an NVIDIA driver reports CUDA 12.x or newer, including CUDA 13.x driver reports; otherwise Annolid uses CPU onnxruntime. On macOS, ONNX acceleration uses CoreML when available rather than a CUDA GPU wheel.

For a non-interactive CPU baseline, use:

curl -sSL https://raw.githubusercontent.com/healthonrails/annolid/main/install.sh | bash -s -- --no-gpu --no-interactive

On Windows PowerShell:

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/healthonrails/annolid/main/install.ps1))) -NoGpu -NoInteractive

Local .venv with uv

For development or reproducible local work, use uv and a repository-local .venv:

git clone --recurse-submodules https://github.com/healthonrails/annolid.git
cd annolid
uv venv .venv --python 3.11
source .venv/bin/activate
uv pip install -e ".[gui]"

The dedicated guide is uv Setup.

If you want ONNX Runtime GPU support in a manual uv environment on Linux or Windows, install Annolid first and then add the GPU wheel:

uv pip install --upgrade --force-reinstall onnxruntime-gpu --extra-index-url https://aiinfra.pkgs.visualstudio.com/PublicPackages/_packaging/onnxruntime-cuda-12/pypi/simple/
python -c "import onnxruntime as ort; print(ort.get_available_providers())"

pip / venv

If you prefer standard Python tooling:

python -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install "annolid[gui]"

To install from source:

git clone --recurse-submodules https://github.com/healthonrails/annolid.git
cd annolid
pip install -e ".[gui]"

Conda

Conda still works well when you want environment management plus FFmpeg and native libraries from conda-forge:

conda create -n annolid-env python=3.11
conda activate annolid-env
conda install -c conda-forge ffmpeg git
git clone --recurse-submodules https://github.com/healthonrails/annolid.git
cd annolid
pip install -e ".[gui]"

Optional Extras

Useful extras currently defined in pyproject.toml include:

  • gui: Qt bindings for the desktop application
  • large_image: TIFF/OME-TIFF metadata and optional streaming backends (tifffile, pyvips, openslide-python)
  • sam3: SAM3-related dependencies
  • image_editing: diffusion/image-editing features
  • text_to_speech: read-aloud and narration features
  • qwen3_embedding: embedding-related utilities
  • mediapipe: MediaPipe-based workflows
  • cowtracker: CowTracker backend dependency
  • remote_video: network/remote video decoding through ffpyplayer
  • annolid_bot: Annolid Bot integrations such as MCP, Playwright, WhatsApp bridge support, and Google Drive/Calendar dependencies

Example:

pip install -e ".[gui,large_image,annolid_bot,text_to_speech]"

Note on large_image

large_image is optional. A normal annolid[gui] install does not require these dependencies, and Annolid's standard image/video annotation workflows continue to work without them.

The large_image extra installs the Python packages, but some platforms also need native runtimes for the fastest backends:

  • pyvips needs a working libvips runtime
  • openslide-python needs a working OpenSlide runtime

If those native libraries are missing, Annolid falls back to tifffile when available. If the full large_image extra is not installed, Annolid still starts normally and falls back to the standard Qt/Pillow image path instead of requiring large-image packages at startup.

Note on remote_video

remote_video is optional. Annolid's default install does not require ffpyplayer, which keeps Python 3.14 installs from failing when no compatible ffpyplayer wheel is available. Install it only if you use Annolid's network/remote video decoding path:

pip install -e ".[remote_video]"

On Python 3.14, ffpyplayer may build from source and require native FFmpeg development headers such as libpostproc.

Verify the Install

Run:

annolid --help
annolid-run --help

Launch the GUI:

annolid

List available model plugins:

annolid-run list-models

Common Post-install Notes

  • Install FFmpeg if video import/export or codec support is incomplete.
  • If ONNX Runtime GPU validation fails, activate the installer-created environment and rerun the repair command printed by the installer.
  • If you use Annolid Bot with MCP or browser automation, install the annolid_bot extra.
  • If qtpy.QtBindingsNotFoundError appears, install the gui extra in the active environment.
  • The gui extra now installs PySide6 as the default Qt binding.

Next Steps

  • Workflows for the main GUI and CLI paths
  • MCP for Annolid Bot integrations
  • SAM 3D for the optional 3D reconstruction setup