Setup¶

Installation ¶

To install BirdNET, you can use pip:

pip install birdnet --user

This will install the latest version of the BirdNET package along with its dependencies.

Ensure reproducibility ¶

To install BirdNET in a reproducible environment, use the repro extra, which pins dependency versions and tries to ensure consistent behavior across setups.

Note

Note that it does not include the latest packages, so bugs fixed in newer versions may still be present. This configuration supports CPU execution only and requires Python 3.12. If you have dependencies that overlap with other packages in your system, installations may fail or crash. It is recommended to install BirdNET in a dedicated virtual environment to avoid conflicts.

pip install birdnet[repro] --user

CUDA Support ¶

To install BirdNET with CUDA support, ensure that you have the NVIDIA GPU driver and CUDA installed on your system. Then, use the following command:

pip install birdnet[and-cuda] --user

Troubleshooting ¶

If you encounter issues with audio file reading, please ensure that libsndfile is installed on your system.

Ubuntu/Debian: sudo apt-get install libsndfile1
macOS (using Homebrew): brew install libsndfile
Windows: Download and install the latest precompiled binaries (e.g., libsndfile-1.2.2-win64.zip) from the official website, extract them and add the folder to path.

Installation (dev)¶

For development purposes, you can clone the repository and install it in editable mode.

Linux & macOS ¶

# requirement: ensure Python 3.12 is installed

# check out repo
git clone https://github.com/birdnet-team/birdnet.git
cd birdnet

# create virtual environment
python3.12 -m venv .venv311
source .venv312/bin/activate

# install uv for faster package installation
python3.12 -m pip install uv

# install package in editable mode with all extra dependencies
python3.12 -m uv pip install -e .[dev,tests,docs,and-cuda]

Windows ¶

# requirement: ensure Python 3.12 is installed

# check out repo
git clone https://github.com/birdnet-team/birdnet.git
cd birdnet

# create virtual environment
py -3.12 -m venv .venv312
.venv312\\Scripts\\activate

# install uv for faster package installation
py -3.12 -m pip install uv

# install package in editable mode with all extra dependencies
py -3.12 -m uv pip install -e .[dev,tests,docs,and-cuda]

Workflows ¶

This section describes common workflows for maintaining and using the BirdNET codebase.

Delete cached Python files ¶

To delete all cached Python files from the source code, use the following command:

find ./src | grep -E "(/__pycache__$|\.pyc$|\.pyo$)" | xargs rm -rf

Run MyPy for type checking ¶

To run MyPy for type checking, use the following command:

# mypy config is in pyproject.toml
mypy

Autoformat code ¶

To autoformat the codebase, use the following command:

autoflake --in-place --remove-all-unused-imports --ignore-init-module-imports ./src/ -r

Run ruff linter ¶

To run the ruff linter, use the following command:

# ruff config is in pyproject.toml
ruff check src/birdnet

# to automatically fix issues
ruff check src/birdnet --fix

Delete shared memory segments ¶

To delete all shared memory segments (e.g., after a crash), use the following command:

# list shared memory segments
ls -lh /dev/shm

# delete all BirdNET shared memory segments, i.e., those starting with "bn_"
rm /dev/shm/bn_*

Run tests ¶

To run the test suite, use the following command:

# requirement: ensure all Python versions (3.11-3.13) are installed

# run all tests for Python 3.11, 3.12, and 3.13
tox

You can also run only specific tests using the following commands (examples):

# run only reproducibility tests for Python 3.12
tox -e py312-repro

# run specific tests with pytest
pytest -m "not repro and (not litert and not gpu)" -n auto

Calculate code coverage ¶

To calculate code coverage, use the following command:

# run all tests with coverage for Python 3.12
tox -e py312-coverage

Deploy package to PyPI ¶

To build and deploy the package to PyPI, use the following commands:

# requirement: ensure code is autoformatted and all tests pass

# upgrade build and twine
python3.12 -m uv pip install --upgrade build twine

# clean previous builds
rm -rf dist/ build/ *.egg-info/

# build source and wheel distributions to create:
# -> dist/birdnet-<version>-py3-none-any.whl
# -> dist/birdnet-<version>.tar.gz
python3.12 -m build -o dist/

# check built distributions: output should be "PASSED" for both files
python3.12 -m twine check dist/*

# check that no __pycache__ files are included
tar -tzf dist/*.tar.gz | grep __pycache__

# upload to PyPI
python3.12 -m twine upload --repository pypi dist/*

Build documentation ¶

To build the documentation locally, use the following command:

# autogenerate doc templates for all modules
# sphinx-apidoc -o docs/ src/birdnet/

# build HTML docs
sphinx-build -b html docs/ docs/_build/html -j auto

# OR: autobuild docs after each change
sphinx-autobuild -b html docs/ docs/_build/html -j auto --watch src/birdnet

Count lines of code ¶

To count the lines of code in the BirdNET source code, use the following command:

pygount src/birdnet --format=summary

Debugging on Raspberry Pi ¶

To debug BirdNET on a Raspberry Pi, you can use the following command:

# copy package and example file to Raspberry Pi
scp dist/birdnet-0.2.10-py3-none-any.whl pi@192.168.2.103:/home/pi/birdnet-0.2.10-py3-none-any.whl
scp example/soundscape.wav pi@192.168.2.103:/home/pi/soundscape.wav

# setup virtual environment on Raspberry Pi
ssh pi@192.168.2.103
sudo apt-get update
sudo apt-get upgrade
python3.12 -m venv .venv312
source .venv312/bin/activate
python3.12 -m pip install --upgrade pip
python3.12 -m pip install wheel uv

# remove previous birdnet installation if exists
python3.12 -m uv pip uninstall birdnet

# install birdnet package from wheel file
python3.12 -m uv pip install /home/pi/birdnet-0.2.10-py3-none-any.whl

# run benchmark script
birdnet-benchmark /home/pi/soundscape.wav --tf-library litert --precision int8

FAQ ¶

Where is application data stored?¶

All BirdNET data (models, benchmarks) is stored in the application-data directory, whose location is platform-specific:

Linux: ~/.local/share/birdnet
macOS: ~/Library/Application Support/birdnet
Windows: %APPDATA%/birdnet

Why is Python 3.10 not supported?¶

Python 3.10 is not supported because it is outdated and misses some typing features, e.g., from typing import Self