Dev

CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.16] - 2026-05-09
+
+### Added
+
+- Add support for overriding BirdNET’s application-data directory via an environment variable `BIRDNET_APP_DATA`, enabling users to place downloaded models/benchmarks in a custom location (useful for deployments with restricted home directories or shared storage).
+
 ### Bugfixes
 
 - Fixed acoustic inference session being aborted on macOS when stats were enabled: hardened parent/child memory tracking against `psutil.AccessDenied`, and replaced the two tracked semaphores with a wrapper that mirrors the count into shared memory so `get_value()` works on macOS (#39)
@@ -269,7 +275,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Initial release
 
-[Unreleased]: https://github.com/birdnet-team/birdnet/compare/v0.2.15...HEAD
+[Unreleased]: https://github.com/birdnet-team/birdnet/compare/v0.2.16...HEAD
+[0.2.16]: https://github.com/birdnet-team/birdnet/compare/v0.2.15...v0.2.16
 [0.2.15]: https://github.com/birdnet-team/birdnet/compare/v0.2.14...v0.2.15
 [0.2.14]: https://github.com/birdnet-team/birdnet/compare/v0.2.13...v0.2.14
 [0.2.13]: https://github.com/birdnet-team/birdnet/compare/v0.2.12...v0.2.13

docs/conf.py

@@ -9,7 +9,7 @@
 project = "birdnet"
 copyright = "2026, Stefan Taubert"
 author = "Stefan Taubert"
-release = "0.2.15"
+release = "0.2.16"
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

docs/setup.rst

@@ -281,6 +281,14 @@ All BirdNET data (models, benchmarks) is stored in the application-data director
 - **macOS:** ``~/Library/Application Support/birdnet``
 - **Windows:** ``%APPDATA%/birdnet``
 
+The default location can be overridden by setting the ``BIRDNET_APP_DATA`` environment variable to any absolute path before the ``birdnet`` package is imported. ::
+
+  # Windows pre-execution script
+  set BIRDNET_APP_DATA=C:\Program Files\BirdNET-Analyzer\birdnet-data
+
+  # Linux / macOS pre-execution script
+  export BIRDNET_APP_DATA=/opt/birdnet-analyzer/birdnet-data
+
 Why is Python 3.10 not supported?
 ^^^^
 

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "birdnet"
-version = "0.2.15"
+version = "0.2.16"
 description = "A Python library for identifying bird species by their sounds."
 readme = "README.md"
 requires-python = ">=3.11, <3.14"

src/birdnet/globals.py

@@ -145,6 +145,8 @@
 
 PKG_NAME = "birdnet"
 
+ENV_VAR_APP_DATA = "BIRDNET_APP_DATA"
+
 # flag for "can be written to" = free
 WRITABLE_FLAG = np.uint8(0)
 

src/birdnet/utils/local_data.py

@@ -4,6 +4,7 @@
 
 from birdnet.globals import (
   ACOUSTIC_MODEL_VERSIONS,
+  ENV_VAR_APP_DATA,
   GEO_MODEL_VERSIONS,
   MODEL_BACKEND_PB,
   MODEL_BACKEND_TF,
@@ -38,6 +39,9 @@ def get_app_data_path() -> Path:
 
 
 def get_birdnet_app_data_folder() -> Path:
+  override = os.getenv(ENV_VAR_APP_DATA)
+  if override is not None:
+    return Path(override).expanduser().resolve()
   app_data = get_app_data_path()
   result = app_data / PKG_NAME
   return result