Installation#

Warning

ethograph is not yet published on PyPI. Until the first release, install directly from the GitHub repository (see Install from source below). All pip install ethograph commands on this page will only work after the package is published.

Prerequisites#

ethograph requires Python 3.11 or later. We recommend installing it in an isolated virtual environment.

Install ffmpeg#

ethograph uses ffmpeg for video and audio processing. Check if it is already installed:

ffmpeg -version

If the command is not found, install it:

  1. Download ffmpeg-release-essentials.zip from gyan.dev.

  2. Extract the zip and copy the bin folder to C:\ffmpeg\bin.

  3. Add C:\ffmpeg\bin to your system PATH:

    • Search for “Environment Variables” in the Start menu.

    • Under System variables, select Path → Edit → New → paste C:\ffmpeg\bin.

  4. Open a new terminal and verify: ffmpeg -version.

brew install ffmpeg

# Debian/Ubuntu
sudo apt install ffmpeg

# Fedora
sudo dnf install ffmpeg

Install uv#

uv is a fast Python package manager. ethograph uses uv for installation regardless of how you create your virtual environment.

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

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Create a virtual environment#

You can use either conda or uv to create the environment — conda is only used for environment creation, not for installing ethograph itself.

conda create -y -n ethograph -c conda-forge python=3.12
conda activate ethograph

uv venv --python=3.12

Activate it:

# macOS / Linux
source .venv/bin/activate

# Windows (PowerShell)
.venv\Scripts\activate

Install the package#

Important

Make sure your virtual environment is activated before running any install commands. You should see the environment name (e.g. (ethograph)) in your terminal prompt.

Core only (library)#

The core package includes the TrialTree data structure, xarray utilities, feature extraction, and label I/O — no GUI, no audio, no NWB. This is useful when you want to use TrialTree as a data structure in your own scripts or pipelines without pulling in GUI dependencies.

uv pip install ethograph

DANDI archive downloads#

To browse and download datasets from the DANDI archive via the GUI wizard:

uv pip install "ethograph[dandi]"

Everything#

Install all optional dependencies (GUI + NWB):

uv pip install "ethograph[all]"

Optional dependency groups#

ethograph uses optional extras to keep the base install lightweight. You can combine them as needed:

Extra

What it adds

audio

Audio waveforms, spectrograms, vocal segmentation

neural

Spike sorting analysis tools (phylib, neo)

dandi

DANDI archive download client (heavy, opt-in)

gui

Full graphical interface (includes audio + neural)

all

Everything above (gui + dandi)

dev

Testing and linting tools

docs

Documentation build dependencies

Combine extras with commas:

uv pip install "ethograph[gui,dandi]"

Install from source#

Use this method while ethograph is not yet on PyPI, or whenever you want to track the latest development version:

git clone https://github.com/Akseli-Ilmanen/ethograph.git
cd ethograph
uv pip install -e ".[gui]"

The -e flag installs in editable mode — code changes take effect immediately without reinstalling.

For developers#

To install ethograph in editable mode with all optional dependencies and development tools, see Contributing.

Update the package#

uv pip install -U "ethograph[gui]"

Hint

If the update doesn’t seem to work, try creating a fresh environment and reinstalling from scratch.

Model training (experimental)#

Warning

Model training is in development and not well documented.

Install PyTorch with the correct CUDA version for your system, then install the model extra along with omegaconf:

conda install pytorch=2.5.1 torchvision=0.20.1 torchaudio=2.5.1 pytorch-cuda=12.1 -c pytorch -c nvidia
uv pip install "ethograph[model]" omegaconf