This edition adds managed Tor v3 onion-service exposure for secure remote access without opening an inbound router port.
A realtime acoustic bird classification system for the Raspberry Pi 5, 4B, 400, 3B+, and 0W2
Icon made by Freepik from www.flaticon.com
This edition is built on the actively maintained Nachtzuster/BirdNET-Pi fork of mcguirepr89/BirdNET-Pi. It follows Nachtzuster's updates while adding a managed Tor onion service for remote dashboard access.
Changes include:
- Backup & Restore
- Web ui is much more responsive
- Daily charts now include all species, not just top/bottom 10
- Bump apprise version, so more notification type are possible
- Swipe events on Daily Charts (by @croisez)
- Support for 'Species range model V2.4 - V2'
- Bookworm and Trixie support
- Experimental support for writing transient files to tmpfs
- Rework analysis to consolidate analysis/server/extraction. Should make analysis more robust and slightly more efficient, especially on installations with a large number of recordings
- Bump tflite_runtime to 2.17.1, it is faster
- Rework daily_plot.py (chart_viewer) to run as a daemon to avoid the very expensive startup
- Managed Tor v3 onion service with a stable
.onionaddress, dashboard controls, protected identity keys, and supported proof-of-work defenses - Lots of fixes & cleanups
!! note: see 'Migrating' on how to migrate from mcguirepr89
BirdNET-Pi is built on the BirdNET framework by @kahst 
Check out birds from around the world
- 24/7 recording and automatic identification of bird songs, chirps, and peeps using BirdNET machine learning
- Automatic extraction and cataloguing of bird clips from full-length recordings
- Tools to visualize your recorded bird data and analyze trends
- Live audio stream and spectrogram
- Automatic disk space management that periodically purges old audio files
- BirdWeather integration -- you can request a BirdWeather ID from BirdNET-Pi's "Tools" > "Settings" page
- Web interface access to all data and logs provided by Caddy
- GoTTY and GoTTY x86 Web Terminal
- Tiny File Manager
- FTP server included
- SQLite3 Database
- Adminer database maintenance
- phpSysInfo
- Apprise Notifications supporting 90+ notification platforms
- Standalone Nostr NIP-17 direct-message notifications with a dedicated BirdNET-Pi sender key
- Localization supported
- Remote dashboard access through a Tor v3 onion service, without port forwarding or a public domain
- A Raspberry Pi 5, Raspberry 4B, Raspberry Pi 400, Raspberry Pi 3B+, or Raspberry Pi 0W2 (The 3B+ and 0W2 must run on RaspiOS-ARM64-Lite)
- An SD Card with the 64-bit version of RaspiOS installed (please use Trixie) -- Lite is recommended, but the installation works on RaspiOS-ARM64-Full as well. Downloads available within the Raspberry Pi Imager.
- A USB Microphone or Sound Card
A comprehensive installation guide is available here. This guide is slightly outdated, so use the installation command below to install this Tor-enabled edition from StellarStoic/BirdNET-Pi.
Please note that installing BirdNET-Pi on top of other servers is not supported. If this is something that you require, please open a discussion for your idea and inquire about how to contribute to development.
Raspberry Pi 3B[+] and 0W2 installation guide available here and also mentioned in the /docs/TOR_HOSTING.md
The system can be installed with:
# Download and run this edition's BirdNET-Pi installer.
curl -fsSL https://raw.githubusercontent.com/StellarStoic/BirdNET-Pi/main/newinstaller.sh | bashThe installer takes care of any and all necessary updates, so you can run that as the very first command upon the first boot, if you'd like.
The installation creates a log in $HOME/installation-$(date "+%F").txt.
The BirdNET-Pi can be accessed from any web browser on the same network:
- http://birdnetpi.local OR your Pi's IP address
- Default Basic Authentication Username: birdnet
- Password is empty by default. Set this in "Tools" > "Settings" > "Advanced Settings"
This edition can expose the BirdNET-Pi dashboard as a Tor v3 onion service. It provides remote access without router port forwarding, public DNS, or directly revealing the visitor's IP address to BirdNET-Pi, and the host's IP address is also hidden from the visitor.
To enable it from the dashboard:
- Open Tools > Settings > Advanced Settings.
- Find Tor Hosting.
- Select Host this BirdNET-Pi on Tor.
- Save the settings and wait up to 60 seconds.
- Open the generated
http://...onionaddress in Tor Browser.
The Tor service can also be enabled, restarted, or disabled under Tools > Services > Tor Onion Service. Disabling it preserves the private identity keys, so the same onion address returns when it is enabled again. To deliberately replace the address, use Reset onion address in Tools > Settings > Advanced Settings > Tor Hosting.
Command-line management is also available:
# Enable the BirdNET-Pi onion service and generate an address when needed.
sudo /usr/local/bin/update_tor_service.sh enable
# Restart an enabled onion service without changing its address.
sudo /usr/local/bin/update_tor_service.sh restart
# Disable exposure while preserving the onion address and private identity.
sudo /usr/local/bin/update_tor_service.sh disable
# Permanently replace the onion identity and generate a new address.
sudo /usr/local/bin/update_tor_service.sh resetImportant security notes:
- An onion address is not a password. Anyone who obtains it can attempt to access the dashboard.
- Set a strong BirdNET-Pi authentication password before enabling remote access.
- Tor protects the network route, but recordings, hostnames, linked resources, and dashboard content can still reveal identifying information.
- Enabling Tor does not disable normal LAN access.
- Keep
/var/lib/tor/birdnet_hidden_service/private and backed up if the onion address must remain permanent. - Tor 0.4.8+ proof-of-work defenses are enabled automatically when the installed Tor package supports them.
See the complete Tor Hosting Guide for troubleshooting, operational guidance, and configuration details.
This edition also supports standalone encrypted Nostr DMs for detection alerts. It is separate from Apprise and uses NIP-17 private direct messages.
Setup path:
- Open Tools > Settings.
- Find Nostr Direct Messages.
- In Receiver, enter your receiver public key (
npub) and the NIP-17 inbox relays used by your Nostr client. - In Sender, click Generate BirdNET-Pi sender key. The UI shows the sender public key (
npub) and keeps the sender private key (nsec) hidden with dots by default. - Optional: paste a dedicated sender private key (
nsec) created only for this device, then derive the matching sender public key (npub). - Click Send Test Nostr DM.
- Enable the notification types you want and click Update Settings.
The Nostr DM title and body support the same detection keywords as Apprise. Use $image to include the current Bird Photo Source image URL in the message.
When Nostr DMs are enabled and configured, BirdNET-Pi also sends the current Tor onion address after the Tor service is enabled, restarted, or reset.
Use the generated BirdNET-Pi sender key only for this device. Do not paste your personal Nostr private key (nsec) into BirdNET-Pi. Manual sender-key import is available only for a separate key created for this device.
Please take a look at the wiki and discussions for information on
- BirdNET-Pi's Deep Convolutional Neural Network(s)
- making your installation public
- backing up and restoring your database
- adjusting your sound card settings
- suggested USB microphones
- building your own microphone
- privacy concerns and options
- beta testing
- and more!
Use the web interface and go to "Tools" > "System Controls" > "Update". If you encounter any issues with that, or suspect that the update did not work for some reason, please save its output and post it in an issue where we can help.
Use the web interface and go to "Tools" > "System Controls" > "Backup" or "Restore". Backup/Restore is primary meant for migrating your data for one system to another. Since the time required to create or restore a backup depends on the size of the data set and the speed of the storage, this could take quite a while.
Alternatively, the backup script can be used directly. These examples assume the backup medium is mounted on /mnt
To backup:
./scripts/backup_data.sh -a backup -f /mnt/birds/backup-2024-07-09.tar
To restore:
./scripts/backup_data.sh -a restore -f /mnt/birds/backup-2024-07-09.tar
x86_64 support is mainly there for developers or otherwise more Linux savvy people. That being said, some pointers:
- Use Debian 12 or 13
- The user needs passwordless sudo
For Proxmox, a user has reported adding this in their cpu-models.conf, in order for the custom TFLite build to work.
cpu-model: BirdNet
flags +sse4.1
reported-model host
/usr/local/bin/uninstall.sh && cd ~ && rm -drf BirdNET-Pi
Before switching, make sure your installation is fully up-to-date. Also make sure to have a backup, that is also the only way to get back to the original BirdNET-Pi. Please note that upgrading your underlying OS to Bookworm is not going to work. Please stick to Bullseye. If you do want Bookworm, you need to start from a fresh install and copy back your data. (remember the backup!)
Run these commands to migrate to this repo:
# Point an existing BirdNET-Pi checkout at this Tor-enabled edition.
git remote remove origin
git remote add origin https://github.com/StellarStoic/BirdNET-Pi.git
# Apply the updates from the newly configured repository.
./scripts/update_birdnet.sh*Hint: A lot of weird problems can be solved by simply restarting the core services. Do this from the web interface "Tools" > "Services" > "Restart Core Services" Having trouble or have an idea? Submit an issue for trouble and a discussion for ideas. Please do not submit an issue as a discussion -- the issue tracker solicits information that is needed for anyone to help -- discussions are not for issues.
PLEASE search the repo for your issue before creating a new one. This repo has nothing to do with the validity of the detection results, so please do not start any issues around "False positives."
Please join a Discussion!! and please join BirdWeather!! I hope that if you find BirdNET-Pi has been worth your time, you will share your setup, results, customizations, etc. HERE and will consider making your installation public.
BirdNET-Pi can also be run as a Homeassistant addon through docker. For more information : https://github.com/alexbelgium/hassio-addons/blob/master/birdnet-pi/README.md
BirdNET-Pi can also be run as as a docker container. For more information : https://github.com/alexbelgium/hassio-addons/blob/master/birdnet-pi/README_standalone.md
- Marie Lelouche's Out of Spaces using BirdNET-Pi in post-sculpture VR! Press Kit
- Research on noded BirdNET-Pi networks for farming
- PixCams Build Guide
- Core-Electronics Build Article
- RaspberryPi.com Blog Post
- MagPi Issue 119 Showcase Article
The bird names are in English by default, but other localized versions are available thanks to the wonderful efforts of @patlevin and Wikipedia. Use the web interface's "Tools" > "Settings" and select your "Database Language" to have the detections in your language.
Are you a lucky ducky with a spare Raspberry Pi? Try Folding@home!