Installation#

1. Install uv#

uv is a fast Python package manager, and the one ethograph installs with.

curl -LsSf https://astral.sh/uv/install.sh | sh

winget install astral-sh.uv

Works from both PowerShell and Command Prompt. winget is built into Windows 11.

2. Install ethograph#

Pick what you want to do, then how you manage environments.

For annotating data, teaching, or trying it out. No virtual environment needed — uv tool keeps ethograph in its own, managed for you:

uv tool install --python 3.12 "ethograph[gui,audio]"
ethograph check     # Linux/WSL only: lists missing system libraries
ethograph launch

ethograph launch says “not recognized” or “command not found”? Run uv tool update-shell once and open a new terminal (see ethograph is not recognized as a command).

Upgrade with uv tool upgrade ethograph, remove with uv tool uninstall ethograph.

For importing ethograph in your own code.

uv venv --python=3.12
source .venv/bin/activate        # Windows: .venv\Scripts\activate
uv pip install "ethograph[gui,audio]"
ethograph check                  # Linux/WSL only: lists missing system libraries

conda create -y -n ethograph -c conda-forge python=3.12
conda activate ethograph
uv pip install "ethograph[gui,audio]"
ethograph check                  # Linux/WSL only: lists missing system libraries

conda only creates the environment; ethograph itself is installed with uv.

Upgrade with uv pip install -U "ethograph[gui,audio]"; if that doesn’t seem to take effect, start from a fresh environment.

For action segmentation and event spotting. PyTorch is installed first, separately.

uv venv --python=3.12
source .venv/bin/activate        # Windows: .venv\Scripts\activate
uv pip install --torch-backend=auto torch torchvision
uv pip install "ethograph[gui,audio,model]"
ethograph check                  # Linux/WSL only: lists missing system libraries

conda create -y -n ethograph -c conda-forge python=3.12
conda activate ethograph
uv pip install --torch-backend=auto torch torchvision
uv pip install "ethograph[gui,audio,model]"
ethograph check                  # Linux/WSL only: lists missing system libraries

Creating the environment from conda-forge keeps shared libraries on one channel, avoiding ABI conflicts with the libraries PyTorch/CUDA depend on.

Check PyTorch sees your GPU:

python -c "import torch; print(torch.cuda.is_available())"

Danger

Linux/WSL: missing system libraries can cause a black or failed launch. ethograph check lists what to install; see Linux: system libraries.

For an editable development install, see Contributing.

Optional extras#

Extras are combined with commas, e.g. "ethograph[gui,audio,dandi]". Plain ethograph is the library alone: TrialTree, xarray utilities, feature extraction and label I/O.

Extra

What it adds

gui

Graphical interface (PyQtGraph, pygfx/pynaviz, neural tools)

audio

Waveform, spectrogram, playback (sounddevice etc.)

model

Segmentation and spotting pipelines — install PyTorch first (see Train models)

dandi

Download client for the DANDI archive

proxy

Bundled ffmpeg for smoother scrubbing in long videos

dev

Testing and linting tools

docs

Documentation build dependencies

Note

On Linux, audio also needs PortAudio and the ALSA plugins from your distribution — part of the one line in Linux: system libraries. Silent playback: see Silent audio on Linux.

proxy — ethograph works fully without ffmpeg; ffmpeg only generates low-resolution proxies that make seeking long, high-resolution videos smoother. A system ffmpeg is picked up automatically, or set ETHOGRAPH_FFMPEG. The bundled one has no NVENC, so GPU proxy encoding falls back to libx264; for NVENC use conda install -c conda-forge ffmpeg.

PosePAL keypoint fill (GPU only) — the spline and optical-flow fills come with gui; PosePAL needs torch and CoTracker3 (see 5. Fill):

uv pip install --torch-backend=auto torch "cotracker @ git+https://github.com/facebookresearch/co-tracker.git@82e02e8029753ad4ef13cf06be7f4fc5facdda4d"

Where settings live#

Global settings live in ~/.ethograph (override with ETHOGRAPH_HOME):

~/.ethograph/
├── gui_settings.yaml   # your layout, playback and dialog folders
├── logs/               # one log per session
├── cache/              # derived media: video proxies, extracted audio,
│                       # example datasets, downloaded weights — safe to delete
└── defaults/           # a starter project, used while no project folder is chosen:
                        # mapping.txt, config/segment.yaml + spot.yaml to copy from,
                        # config/space/ geometries, runs/lightgbm/ lightgbm models,
                        # workflows/, wizard/ notebooks

An older home folder is rearranged into this shape the first time the GUI starts.