FAQ

Is it accurate? Which model does it use?

A new install uses BirdNET V2.4 with its v2 occurrence filter — the network BirdNET-Pi and birdnet-go run — and BirdNET-Pi’s own defaults (CONFIDENCE 0.70, SENSITIVITY 1.25, and the human-sound rule on). Same audio, same detections says what was measured against BirdNET-Pi’s own code and where the two still differ. The BirdNET+ V3.0 preview is a different model, an explicit choice (--classifier birdnet-v3): it hears 4.5-second windows rather than 3, reports calibrated probabilities rather than raw scores, and covers about 11 500 species rather than 6 500, so its detections are not BirdNET-Pi’s and are not meant to be. Up to v0.17.1 V3.0 was installed for everyone, and a station that already runs it keeps it: no install or update changes a running station’s model.

The V2.4 files (about 85 MB) are installed on the first run, each checked against a SHA-256 compiled into the binary; see Installation for where they come from. The V3.0 files (541 MB, plus a 14 MB occurrence model) come from this project’s model release, with Zenodo as the fallback.

Do I need a Raspberry Pi?

No. It runs on any x86_64 Linux machine too. The Pi 5 is recommended and the Pi 4B and 400 are supported; older boards such as the 3B+ and Zero 2 W are not supported targets (see Hardware). There’s no Python interpreter or virtualenv overhead around the model, so it’s happy on modest hardware.

Does it work offline / without internet?

Yes, once set up. The only things that need the network are the one-time model install, optional Wikipedia photo caching, and any notification/upload channels you enable. The UI itself is fully self-contained — all fonts are embedded in the binary and it never calls out to a CDN.

Does it need a camera, or just a microphone?

Either. Point it at a USB microphone, or at an RTSP stream from an IP camera (many bird-box and feeder cams expose one). You can run several RTSP sources at once. See Audio & Microphones.

Where are my recordings and database stored?

Under /data in Docker (a named volume) or under the data directory on bare metal (~/BirdNet-Behavior for the service user): the SQLite birds.db, the recordings/ clips, the model (models/ on bare metal, /data/model in Docker) and the species-image cache (image_cache/ on bare metal, /data/cache in Docker).

How do I keep a recording I love from being deleted?

Retention is disk-based by default — the oldest clips are purged once the disk fills past the threshold — with an optional age limit (Keep Clip Audio (days) / CLIP_RETENTION_DAYS) that is off unless you set it. Lock any detection (on the Today page) to pin its recording permanently; locked clips are exempt from both. See Backups & Recovery.

Is the dashboard exposed on my network? Do I need a login?

By default the dashboard binds to all interfaces (0.0.0.0:8502), so it’s reachable from any device on your LAN. Viewing needs no login; the /admin* panel, the Settings management tabs and every action that changes something are password-protected. A fresh bare-metal install auto-generates that password for you. To restrict the dashboard to the local machine, set BIRDNET_LISTEN=127.0.0.1:8502 and reach it via SSH tunnel or VPN. For encryption on the LAN, --tls-mode self-signed serves HTTPS on 8503 without a second daemon. Still don’t port-forward it to the internet — put a reverse proxy with a publicly-trusted certificate, or a VPN, in front. See Remote Access & Security.

How do I find or reset the admin password?

The bare-metal installer auto-generates a strong admin password (username admin) and prints it once in the post-install summary, storing it as CADDY_PWD in /etc/birdnet/birdnet.conf. To set your own, edit that file (or the CADDY_PWD environment variable / .env under Docker) and restart:

sudo nano /etc/birdnet/birdnet.conf   # set CADDY_PWD=your-new-password
sudo systemctl restart birdnet-behavior

Editing CADDY_PWD to a new value replaces the admin password at the next restart. A password changed on the Accounts page is kept across restarts instead: the station records which CADDY_PWD it last applied (as a hash, in admin-password.applied beside the database) and does not put an unchanged one back over it. The log says so at warning level on every start while CADDY_PWD is still set. A station upgraded from a release that did not keep that record applies CADDY_PWD once, at its first start, and keeps the record from then on. Remove CADDY_PWD once you have signed in. Sign in as admin — that is the account the dashboard seeds. CADDY_USER is read from the process environment only, so setting it in birdnet.conf does not rename it (it does work under Docker). Clearing CADDY_PWD leaves /admin open to anyone who can reach the dashboard.

What happens to my records if the SD card dies?

Without offsite backups, they go with it. The weekly snapshot the station takes automatically lives in backups/ beside the database, on the same card — it protects against a corrupt page or a bad import, not against the card itself, which in a box on a fence post is a when.

Set OFFSITE_BACKUP=s3 or OFFSITE_BACKUP=sftp (plus OFFSITE_PASSPHRASE) and each weekly snapshot is encrypted on the station and uploaded to an object store or an SSH host. Encryption is not optional and not configurable: your database is a log of what is around your house and when you are there, and neither a bucket provider nor an SFTP host should hold the key.

The passphrase is the only thing that opens those files. It is not stored anywhere, not derivable from the backup, and not known to anyone else — write it down somewhere that is not this station. Restoring is birdnet-behavior --decrypt-backup <file> --out <path>.

See Backups & Recovery.

Why did turning on repeat confirmation change nothing?

Almost certainly because the analysis windows do not overlap. The filter asks how many of the windows within six seconds heard the same species — and with no overlap, six seconds is two 3-second windows, so “20% of them” rounds up to one, which every detection already satisfies.

Set BIRDNET_OVERLAP as well. birdnet-behavior --doctor reports which side of that line your station is on, the dropdown on the settings page prints the overlap each level needs, and the daemon logs a warning at startup when the level it was given cannot reject anything. See Tuning.

Do I need anything special for behavioral analytics?

No. The DuckDB engine behind the deeper behavioral views — activity sessions, species retention, next-species prediction, year-on-year trends — is built into every release and on by default. The installer runs the service with --analytics-db and Docker compose sets BIRDNET_ANALYTICS_DB, so there is no separate build, flag, or image to pick. (From source it is a default Cargo feature — --no-default-features leaves it out. On a very low-RAM board you can turn it off by passing an empty path, --analytics-db "" in the unit or BIRDNET_ANALYTICS_DB: "" in a compose override — removing the flag only falls back to <database>.duckdb; see Troubleshooting.)

Can I use it commercially?

No. BirdNet-Behavior is licensed CC BY-NC-SA 4.0, matching upstream BirdNET and BirdNET-Pi — non-commercial use only. See Credits & License.

How do I update?

• Docker: docker compose pull && docker compose up -d.
• Bare metal: sudo bash install.sh update (or re-run the installer). The Check for Updates button on /admin/system — and GET /admin/update/check — only tells you whether a newer release exists; nothing in the UI applies it.
• Your database, recordings and cached model are preserved across updates.

It’s not detecting anything — what now?

Almost always an audio-source problem. Run birdnet-behavior --doctor (as the account the service runs as; or open /admin/doctor behind the admin login), confirm a source is set and reachable, and check the level meter on Audio & Microphones. The Troubleshooting guide has step-by-step recipes.