BirdNET-Pi Docker Installation Guide

I maintain this and other Home Assistant add-ons in my free time: keeping up with upstream changes, HA changes, and testing on real hardware takes a lot of time (and some money). I use around 5-10 of my >110 addons so regularly I install test machines (and purchase some test services such as vpn) that I don't use myself to troubleshoot and improve the addons

If this add-on saves you time or makes your setup easier, I would be very grateful for your support!

Addon informations

This guide provides instructions on how to install and run the BirdNET-Pi container using Docker Compose without dependency on HomeAssistant.

Note : For usage as an HomeAssistant addon, see here

Thanks to @gotschi for the initial Docker Compose

Prerequisites

Ensure you have the following installed on your system:

Installation

Create a directory for BirdNET-Pi

mkdir -p ~/birdnet-pi && cd ~/birdnet-pi

Create a docker-compose.yml file Create and open the file with:

nano docker-compose.yml

Copy and paste the following configuration:

services:
  birdnet-pi:
    container_name: birdnet-pi
    image: ghcr.io/alexbelgium/birdnet-pi-amd64:latest # or ghcr.io/alexbelgium/birdnet-pi-aarch64:latest depending on your system
    restart: unless-stopped
    ports:
      - "8001:8081"  # Used to access WebUI
      - "80:80"  # Optional: set to 80 to use Caddy's automatic SSL. Can otherwise be set to null to avoid opening an additional port
    environment:
      - TZ=Europe/Vienna  # Optional: Set your timezone according to https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
      - BIRDSONGS_FOLDER=/config/BirdSongs  # Folder to store bird songs, be sure to use a path that is mapped to a volume (such as /config)
      - LIVESTREAM_BOOT_ENABLED=false  # Enable/disable livestream on boot
      - Use_tphakala_model_v2=false  # Switch to BirdNET-Go classifier files
      - ssl=false  # Enable/disable SSL
      - certfile=fullchain.pem  # SSL certificate file (located in /ssl/)
      - keyfile=privkey.pem  # SSL key file (located in /ssl/)
      - pi_password=  # Optional: Set web terminal password for user `pi`
      - MQTT_HOST_manual=  # Optional: Manual MQTT host
      - MQTT_PASSWORD_manual=  # Optional: Manual MQTT password
      - MQTT_PORT_manual=  # Optional: Manual MQTT port
      - MQTT_USER_manual=  # Optional: Manual MQTT user
      - PULSE_SERVER=unix:/tmp/pulseaudio.socket
      - PULSE_COOKIE=/tmp/pulseaudio.cookie

    volumes:
      - ./config:/config  # All your configuration files - and location of the default Birdsongs folder
      - ./ssl:/ssl  # SSL certificates
      - /dev/shm:/dev/shm  # Shared memory
      - /tmp/pulseaudio.socket:/tmp/pulseaudio.socket
      - /tmp/pulseaudio.client.conf:/etc/pulse/client.conf

    devices:
      - /dev/snd:/dev/snd

    group_add:
      - audio

    tmpfs:
      - /tmp # Optional

Start the Container Run the following command in the same directory as docker-compose.yml:
```
docker compose up -d
```
This will start the BirdNET-Pi container in detached mode.
Access BirdNET-Pi Web UI Open your browser and navigate to:
```
http://localhost:8001 # Or whatever port you have configured
```
Replace localhost with your server's IP address if running on another machine. When prompted for credentials in the web terminal, use the username pi and the password defined by pi_password (blank if unset).

troubleshoot

If rtsp feed doesn't work, perhaps you need to add "-rtsp-transport tcp" to your ffmpeg instruction, or allow udp on your network

Updating to the Latest Version

To check for new versions of the container and update:

Check for the latest version Visit the container registry: https://github.com/alexbelgium/hassio-addons/pkgs/container/birdnet-pi-amd64

The latest version tag (e.g., 2025.02.23) will be listed.
Update and restart the container Run the following commands:
```
docker compose pull birdnet-pi
docker compose up -d --force-recreate
```
This pulls the latest image and restarts the container.
Verify the update
```
docker images | grep birdnet-pi
```
This will show the latest downloaded image version.

Stopping and Removing the Container

To stop and remove the container, run:

docker compose down

This will stop and remove BirdNET-Pi while keeping the configuration and recorded songs intact.

Now you're all set to enjoy BirdNET-Pi with Docker! 🐦

5.3 KiB Raw Blame History