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. In practice, Python 3.11 is the safest default for new 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.

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.

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
  • 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
  • annolid_bot: Annolid Bot integrations such as MCP, Playwright, WhatsApp bridge support, and Google Calendar dependencies

Example:

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

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 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.
  • On Python 3.13+, the GUI stack may use PySide6 instead of PyQt5 based on the package metadata.

Next Steps

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