diff --git a/Dockerfile b/Dockerfile
index 287af0c8..d1f2234b 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -10,6 +10,11 @@ ARG PYTHON_VERSION=3.13.15
 # If BUILD_FROM is set (Home Assistant), use it; otherwise use python-slim.
 FROM ${BUILD_FROM:-python:${PYTHON_VERSION}-slim} AS builder
 
+# Home Assistant supplies BUILD_VERSION from config.yaml. Use it for the
+# installed package as well as the dashboard when building an add-on.
+ARG BUILD_VERSION=dev
+ENV EOS_BUILD_VERSION=${BUILD_VERSION}
+
 # uv: pinned, copied as a static binary (no extra Python packages installed).
 COPY --from=ghcr.io/astral-sh/uv:0.12.7 /uv /bin/uv
 
@@ -63,6 +68,8 @@ LABEL \
     org.opencontainers.image.source="https://github.com/Akkudoktor-EOS/EOS" \
     org.opencontainers.image.licenses="Apache-2.0"
 
+ENV EOS_BUILD_VERSION=${BUILD_VERSION}
+
 ENV EOS_DIR="/opt/eos"
 # Create persistent data directory similar to home assistant add-on
 # - EOS_DATA_DIR: Persistent data directory
diff --git a/src/akkudoktoreos/core/version.py b/src/akkudoktoreos/core/version.py
index b498bdec..c0610272 100644
--- a/src/akkudoktoreos/core/version.py
+++ b/src/akkudoktoreos/core/version.py
@@ -323,8 +323,15 @@ def _version_calculate() -> str:
 # Project version information
 # ---------------------------
 
-# The version
-__version__ = _version_calculate()
+# Home Assistant passes the add-on's config.yaml version as BUILD_VERSION. A
+# Docker build without a concrete version uses "dev" (or a branch name), so
+# keep the source-derived version in that case.
+_build_version = os.getenv("EOS_BUILD_VERSION", "")
+__version__ = (
+    _build_version
+    if re.fullmatch(r"\d+\.\d+\.\d+(?:\.dev\d+)?", _build_version)
+    else _version_calculate()
+)
 
 
 # -------------------
diff --git a/tests/test_version.py b/tests/test_version.py
index 872ce1a9..0a6b3717 100644
--- a/tests/test_version.py
+++ b/tests/test_version.py
@@ -1,4 +1,5 @@
 # tests/test_version.py
+import os
 import subprocess
 import sys
 from pathlib import Path
@@ -299,6 +300,33 @@ def test_get_version_prints_non_empty():
     assert len(version.split(".")) >= 3, "Version should have at least MAJOR.MINOR.PATCH"
 
 
+def test_get_version_uses_home_assistant_build_version():
+    """The installed package and EOSdash use the add-on's advertised version."""
+    expected = "0.3.0.dev2608221553448643"
+    env = {**os.environ, "EOS_BUILD_VERSION": expected}
+    result = subprocess.run(
+        [sys.executable, str(GET_VERSION_SCRIPT)],
+        capture_output=True,
+        text=True,
+        check=True,
+        env=env,
+    )
+    assert result.stdout.strip() == expected
+
+
+def test_get_version_ignores_unversioned_docker_build():
+    """The default Docker build argument must not become the package version."""
+    env = {**os.environ, "EOS_BUILD_VERSION": "dev"}
+    result = subprocess.run(
+        [sys.executable, str(GET_VERSION_SCRIPT)],
+        capture_output=True,
+        text=True,
+        check=True,
+        env=env,
+    )
+    assert result.stdout.strip() == _version_calculate()
+
+
 # --- 2️⃣ Test update_version.py on multiple file types ---
 def test_update_version_multiple_formats(tmp_path):
     py_file = write_file(tmp_path / "version.py", '__version__ = "0.1.0"\n')