Skip to content

Installation

Packaging, installer tiers, frozen app policy, and release artifact rules are documented in Packaging and Distribution.

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.

Named installer profiles keep common setups reproducible:

  • minimal: GUI/core annotation setup with the smallest optional footprint
  • gui: default GUI plus ml,tracking,cutie
  • workstation: GUI plus tracking,sam3,training
  • full: GUI plus the all extra

Example workstation install:

curl -sSL https://raw.githubusercontent.com/healthonrails/annolid/main/install.sh | bash -s -- --profile workstation

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
  • ml: general ML/model runtime dependencies such as PyTorch, Transformers, Hugging Face Hub, ONNX Runtime, Hydra/OmegaConf, and COCO tooling
  • test: dependencies needed to import and run the default test collection
  • audio: audio loading/playback helpers (librosa, sounddevice)
  • ai_chat: OpenAI-compatible and Anthropic SDKs for hosted LLM providers
  • training: TensorBoard support for training dashboards and projector views
  • yolo: Ultralytics YOLO/YOLOE workflows and tracker matching helpers
  • cutie: Cutie video object segmentation tracking runtime
  • tracking: common tracking workstation runtime, including PyTorch, ONNX Runtime, Cutie-style config dependencies, and YOLO matching helpers
  • realtime: serial and ZMQ dependencies for realtime/hardware integrations
  • onnx_gpu: Windows/Linux ONNX Runtime CUDA provider
  • 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
  • bot: Annolid Bot integrations plus memory dependencies
  • memory: vector database dependencies for fast Annolid Bot memory
  • all: convenience profile for full-feature workstations

Example:

pip install -e ".[gui,sam3,yolo,training,ai_chat]"

Annolid's base package includes pycocotools so mask/RLE polygon paths are available in default installs. The one-line installer's default gui profile also installs the ml, tracking, and cutie extras so common model and tracking workflows are available immediately. Use --profile minimal / -Profile minimal only when you need the smallest GUI/core annotation setup.

SAM-related packages, hosted AI providers, realtime hardware, large-image backends, Bot integrations, audio helpers, image editing, and text-to-speech remain explicit extras. If one of those features is not installed, Annolid should start normally and show an install hint when that feature is opened.

The one-line installers also keep optional SAM-HQ out of the default path. SAM-HQ is attempted only when a SAM-related extra such as sam3 or the all profile is selected. This avoids a default GitHub source install on machines that only need the GUI/core annotation workflow.

Cutie tracking is also repairable from a minimal install. If a user starts Cutie tracking and one of the Cutie runtime packages is missing, Annolid attempts to install the missing packages into the active environment and then continues loading the tracker. Set ANNOLID_AUTO_INSTALL_CUTIE_DEPS=0 to disable automatic installation and show the exact python -m pip install ... command instead.

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 YOLO/YOLOE commands are missing, install annolid[yolo].
  • If hosted LLM providers are unavailable, install annolid[ai_chat].
  • If audio recording/playback is unavailable, install annolid[audio] or annolid[text_to_speech].
  • 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