There are three ways to install, depending on how you work:
pixi (recommended) — a reproducible, cross-platform environment. Best choice if you’re comfortable with a terminal.
pip — if you already manage your own Python / JupyterLab environment.
Desktop app — a no-code, no-terminal download for the small set of users who don’t work in Python tooling at all.
1. pixi (recommended)¶
pixi builds an isolated, lock-fileable environment and pulls both conda-forge
packages (Python, JupyterLab) and PyPI packages (jupyter-bioacoustic) in one step.
Quick start (new project)¶
pixi init my-annotations
cd my-annotations
pixi add jupyterlab "python>=3.11" # conda-forge
pixi add --pypi jupyter-bioacoustic # PyPI
pixi run jupyter labOr declare it in pixi.toml / pyproject.toml¶
[tool.pixi.dependencies]
python = ">=3.11"
jupyterlab = ">=4.0,<5"
[tool.pixi.pypi-dependencies]
jupyter-bioacoustic = ">=0.9,<1.0"Then pixi install and pixi run jupyter lab.
2. pip¶
If you already have a Python ≥ 3.9 environment with JupyterLab:
pip install jupyter-bioacousticOr install a specific release wheel from GitHub Releases (no Node.js or build step needed):
pip install jupyter_bioacoustic-<version>-py3-none-any.whlSome sources need packages that aren’t installed by default; see Requirements.
3. Desktop app (no-code)¶
A double-click desktop app (no terminal, no pip, no pixi) that runs the annotator in your browser
via a menu-bar / system-tray icon. Download it from
GitHub Releases (since v0.9.3):
macOS —
JupyterBioacoustic-macos-arm64.zip(Apple Silicon) or-x86_64.zip(Intel)Windows —
JupyterBioacoustic-windows-x86_64.zip(not yet tested on Windows)
Command-line tools (optional)¶
The app is self-contained, so its jba CLI (jba lab, jba validate, …) isn’t on your PATH. If you
do want it in a terminal, add a small shell function pointing at the app’s bundled environment:
# macOS (zsh)
cat >> ~/.zshrc <<'EOF'
jba() {
local d="$HOME/Library/Application Support/JupyterBioacoustic/env/.pixi/envs/default/bin"
PATH="$d:$PATH" "$d/jba" "$@"
}
EOF
source ~/.zshrc# Windows (PowerShell) — open a new terminal afterward
Add-Content $PROFILE @'
function jba {
$e = "$env:LOCALAPPDATA\JupyterBioacoustic\env\.pixi\envs\default"
$env:PATH = "$e;$e\Scripts;$e\Library\bin;$env:PATH"
& "$e\Scripts\jba.exe" @args
}
'@(if you’ve never used a PowerShell profile, you may first need
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.)
Uninstalling¶
From the app: tray icon → Uninstall… — it asks for confirmation, then removes the app and its downloaded environment.
From a terminal (quit the app first, via tray → Quit):
# macOS
rm -rf ~/Library/Application\ Support/JupyterBioacoustic
rm -rf /Applications/JupyterBioacoustic.app ~/Applications/JupyterBioacoustic.app
rm -f ~/Applications/"Set JupyterBioacoustic Folder.command" \
/Applications/"Set JupyterBioacoustic Folder.command"# Windows (PowerShell)
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\JupyterBioacoustic"
Remove-Item -Force "$env:APPDATA\Microsoft\Windows\Start Menu\Programs\Jupyter Bioacoustic.lnk"Troubleshooting: blank or crashed browser tab¶
If the browser opens to a blank or crashed (grey) page, the app itself is fine — the menu-bar / system-tray icon is still running, and the problem is your browser’s renderer (this commonly happens right after the browser auto-updates in the background). Fix it:
Fully quit your browser (Cmd-Q on macOS — not just the window) and reopen it, then click the tray icon → Open in Browser again. A clean relaunch loads the updated browser properly.
If it persists, clear the browser’s GPU cache (Chrome: quit, then remove
~/Library/Application Support/Google/Chrome/*/GPUCache), or open the app in a different browser.
The tray menu’s “Page blank or crashed? — Help” item shows these same steps.
Requirements¶
Python ≥ 3.9
JupyterLab ≥ 4.0
Optional packages, depending on your sources:
duckdb— SQL (SELECT ...) datagoogle-cloud-storage—gs://audio, data and sync (pip install "jupyter-bioacoustic[gcs]")
Remote FLAC and WAV audio is read by byte range (only the clip being played is downloaded); other
formats are downloaded and cached in full. No ffmpeg is needed.
The extension auto-registers on install — just launch JupyterLab and go.
See the Development guide on the wiki for building from source.