Troubleshooting#

Report bugs on GitHub Issues. If possible:

In the top bar, Help ▸ Print current state. Share this message along with your error.
If you have data loading problems, send some sample data to akseli.ilmanen@gmail.com, so I can test it myself.

Quick fixes#

Problem	Solution
Unexpected error in the GUI	Save labels (`Ctrl + S`), then restart the GUI. Save semi-regularly!
Error with user settings	In the top bar, first try Help ▸ Reset local settings (this dataset). If that does not help, use Help ▸ Reset global settings (gui_settings.yaml).

FAQ#

My dataset format is not supported#

I/O support for new data formats is actively being expanded. If your format is not yet represented, please send a sample dataset to akseli.ilmanen@gmail.com and I will work on adding loading support for it.

What does this button do?#

A lot of buttons, spinners, dropdowns, etc. have a little description tooltip when you hover over them.

Installation fails with “resolution-too-deep”#

This happens when using plain pip to install ethograph with extras like [gui] or [all]. The dependency tree (pygfx + movement + pynwb) is too complex for pip’s resolver.

Fix: Use uv instead of pip:

uv pip install "ethograph[all]"

See Installation for full instructions.

`ethograph` is not recognized as a command#

The terminal reports something like:

The term 'ethograph' is not recognized as the name of a cmdlet, function,
script file, or operable program.

The install worked — the ethograph command just isn’t on your PATH yet. uv tool install puts it in uv’s own bin directory, which uv has to register with your shell:

uv tool update-shell

Then close the terminal and open a new one. PATH is only read when a shell starts, so the current window will keep reporting the same error. After that, ethograph launch works from any directory.

Linux: system libraries the wheels need#

The Python wheels bring their own Qt, OpenGL bindings and wgpu, but on Linux they load a few shared libraries from the distribution. A desktop install usually has them; a minimal container, a lab server or a fresh WSL distro usually does not. Install them once, before the first launch:

Debian / Ubuntu / WSL

sudo apt install libgl1 libopengl0 libegl1 libxcb-cursor0 libxkbcommon-x11-0 \
    libxcb-icccm4 libxcb-keysyms1 libxcb-image0 libxcb-render-util0 \
    libxcb-shape0 libxcb-xinerama0 libfontconfig1 libdbus-1-3 \
    libvulkan1 mesa-vulkan-drivers \
    libportaudio2 libasound2-plugins

Fedora / RHEL

sudo dnf install mesa-libGL libglvnd-opengl mesa-libEGL xcb-util-cursor \
    libxkbcommon-x11 xcb-util-wm xcb-util-keysyms xcb-util-image \
    xcb-util-renderutil libxcb fontconfig dbus-libs vulkan-loader \
    mesa-vulkan-drivers portaudio alsa-plugins-pulseaudio

The last line of each is only needed with the audio extra: PortAudio itself, plus the ALSA→PipeWire/PulseAudio bridge without which PortAudio cannot reach a modern sound server.

Run the preflight to see which are still missing on your machine — it prints the exact install line for your distribution:

ethograph check

ethograph launch prints the same warning before it opens a window, so if a launch ends in one of the errors below, scroll up: the fix is already on screen. (The libxcb-* entries are only needed when Qt runs on X11 — on a Wayland desktop or WSLg the check leaves them out. The ALSA bridge is a plugin rather than a library, so it is the one item the check cannot see.)

Each missing library fails in its own words:

You see	What is missing
`OpenGL.platform.ctypesloader \| Failed to load library ( 'libOpenGL.so.0' )`	`libopengl0` (and usually `libgl1`) — PyOpenGL’s GLVND dispatch
`qt.qpa.plugin: Could not load the Qt platform plugin "xcb"`	the xcb libraries (`libxcb-cursor0`, `libxkbcommon-x11-0`, …)
The GUI opens but the video panel stays black, or wgpu reports no adapter	`libvulkan1` + `mesa-vulkan-drivers`
`OSError: PortAudio library not found`	`libportaudio2` (audio extra)
The GUI runs but playback is silent	`libasound2-plugins` — see Silent audio on Linux

See Windows Subsystem for Linux (WSL) for Windows Subsystem for Linux.

Windows Subsystem for Linux (WSL)#

The GUI runs under WSLg (Windows 11, or wsl --update on Windows 10). A WSL distro is a minimal install, so start with the system libraries above — every one of them is typically missing — then ethograph check.

Qt runs on Wayland there, which needs none of the libxcb-* libraries; only if you set QT_QPA_PLATFORM=xcb yourself do they become mandatory (the check reads that variable). Video is best-effort: wgpu does not officially support WSL and falls back to mesa’s software renderer or Microsoft’s dzn driver, both in mesa-vulkan-drivers. If the video panel stays black after installing them, run ethograph natively on Windows — the data on /mnt/c/... is the same data.

Silent audio on Linux#

If playback is silent, check what PortAudio sees:

python -c "import sounddevice as sd; print(sd.query_devices())"

A default device of [-1, -1] means PortAudio found no device. On a PipeWire/PulseAudio desktop this is almost always the missing ALSA bridge — install it and restart ethograph:

sudo apt install libasound2-plugins pipewire-alsa

(Debian/Ubuntu’s bundled PortAudio only speaks ALSA, so it needs this bridge to reach a modern sound server.) Routing playback through pw-play/paplay instead makes audio audible but not sample-accurately synced, so it isn’t suitable for precise annotation.

Supported audio formats#

The waveform, spectrogram and playback read audio through audioio (libsndfile): .wav (recommended — fastest and best tested), .flac, .ogg, and .mp3 with a recent libsndfile (>= 1.1).

Audio embedded in a video (.mp4/.mov/.avi) is decoded to a WAV first, never read in place — libsndfile reads no video container, and an AAC track has no sample-exact random access. The first time a video is used as an audio source, its track is decoded once (through PyAV, bundled with the gui extra) into ~/.ethograph/cache/audio_tracks/ and every reader opens that file instead. This happens both when dropping a video with the “Extract the audio for audio trace / spectrogram plots” box ticked and when an alignment or .nwb audio stream points at the video itself. The cache is keyed by path, size and mtime, so a re-recorded video is never served a stale extract; delete the folder any time to reclaim the space. A file that cannot be decoded produces one log line naming it and the reason.

Separate audio files are still better when you can supply them: AAC encoder priming can shift an extracted track by a few milliseconds, and the extract is uncompressed. Converting in bulk up front is faster for a whole project:

for f in *.mp4; do ffmpeg -i "$f" -vn -acodec pcm_s16le "${f%.mp4}.wav"; done

Opening `.tsv` label files in Excel#

Excel on Windows may not correctly parse .tsv files when double-clicked due to regional delimiter settings.

Automatic fix: EthoGraph automatically registers .tsv files to open correctly in Excel with tab delimiters the first time you run it. On Windows this writes to the current-user registry (no admin prompt); on macOS it uses duti if installed.

If the association is not working, you can re-run it manually:

from ethograph.utils.download import ensure_default_configs
ensure_default_configs()

Manual alternative:

Open Excel -> File -> Open -> Browse
Change file filter to “All Files (*.*)”
Select the .tsv file
In the Text Import Wizard, select Tab as delimiter