Home-Assistant-Konfiguration mit Packages ordnen

Veröffentlicht am 27. August 2026 · Geschätzte Lesezeit: 5 Minuten

Mit Packages fasst du alle YAML-Bausteine einer Funktion oder eines Raums in einer Datei zusammen. Ein Paket kann zum Beispiel Helfer, Sensoren und Automationen gemeinsam enthalten, statt sie auf mehrere große Dateien zu verteilen. Das macht Sicherungen, Fehlersuche und spätere Änderungen übersichtlicher. Für die erste Umstellung brauchst du etwa 15 Minuten.

Voraussetzungen

• Eine laufende Home-Assistant-Installation
• Zugriff auf den Konfigurationsordner mit configuration.yaml
• Ein Texteditor, zum Beispiel File editor oder Studio Code Server
• Ein aktuelles Home-Assistant-Backup

1. Konfigurationsordner sichern

Erstelle zuerst unter Einstellungen → System → Backups ein vollständiges Backup. Bei Home Assistant Container sicherst du zusätzlich den eingebundenen Konfigurationsordner auf dem Docker-Host.

Falls du die Dateien per Terminal verwaltest, kannst du im Konfigurationsordner eine zusätzliche Kopie der Hauptdatei anlegen:

cp configuration.yaml configuration.yaml.bak

Der Befehl wird im Ordner ausgeführt, in dem configuration.yaml liegt.

2. Packages aktivieren

Öffne configuration.yaml. Ergänze unter dem bereits vorhandenen Schlüssel homeassistant: die Zeile packages. Gibt es den Schlüssel noch nicht, kannst du den gesamten Block einfügen:

homeassistant:
  packages: !include_dir_named packages

Existiert homeassistant: bereits, darfst du ihn kein zweites Mal anlegen. Ergänze nur die eingerückte Zeile:

homeassistant:
  country: DE
  packages: !include_dir_named packages

!include_dir_named lädt jede YAML-Datei aus dem Ordner packages. Der Dateiname wird dabei zum Paketnamen. Dateinamen müssen deshalb auch in Unterordnern eindeutig sein.

Einrückung genau übernehmen

YAML verwendet Leerzeichen zur Strukturierung. packages: muss genau zwei Leerzeichen unter homeassistant: eingerückt sein. Verwende keine Tabulatoren.

3. Packages-Ordner anlegen

Lege neben configuration.yaml einen Ordner namens packages an. Im Terminal im Home-Assistant-Konfigurationsordner geht das so:

mkdir -p packages

Erstelle darin eine erste Datei:

nano packages/testlicht.yaml

Verwende für Paketdateien kurze, kleingeschriebene Namen ohne Leerzeichen, zum Beispiel waschkueche.yaml oder fensterwarnung.yaml.

4. Erstes Testpaket einfügen

Füge in packages/testlicht.yaml dieses harmlose Beispiel ein:

input_boolean:
  testlicht_aktiv:
    name: Testlicht aktiv
    icon: mdi:lightbulb-check

automation:
  - alias: "Paket-Testlicht einschalten"
    id: paket_testlicht_einschalten
    triggers:
      - trigger: state
        entity_id: input_boolean.testlicht_aktiv
        to: "on"
    actions:
      - action: persistent_notification.create
        data:
          title: "Package funktioniert"
          message: "Die Konfiguration aus packages/testlicht.yaml wurde geladen."

Die Datei enthält einen Helfer und eine Automation als zusammengehöriges Paket. Es sind keine Platzhalter enthalten. Die Benachrichtigung erscheint nur innerhalb von Home Assistant und steuert kein echtes Gerät.

Warum kein zusätzlicher Paketname?

Bei !include_dir_named liefert bereits der Dateiname testlicht.yaml den Paketnamen. Der Inhalt beginnt deshalb direkt mit input_boolean: und automation:. Eine zusätzliche Ebene testlicht: wäre falsch.

5. Konfiguration prüfen

Öffne Entwicklerwerkzeuge → YAML und starte Konfiguration prüfen. Je nach Installationsart kannst du alternativ im Terminal den passenden Befehl verwenden.

Bei Home Assistant OS oder einer Supervised-Installation lautet er:

ha core check

Bei Home Assistant Container führst du die Prüfung auf dem Docker-Host aus. Ersetze <container-name> durch den Namen deines Home-Assistant-Containers:

docker exec <container-name> python -m homeassistant --script check_config --config /config

Starte Home Assistant nur neu, wenn die Prüfung erfolgreich war.

6. Home Assistant neu starten

Starte Home Assistant über Einstellungen → System → Neu starten neu. Bei einer Container-Installation kannst du auf dem Docker-Host auch diesen Befehl verwenden; ersetze wieder <container-name>:

docker restart <container-name>

Öffne danach Einstellungen → Geräte & Dienste → Helfer. Dort sollte Testlicht aktiv erscheinen. Schalte den Helfer ein; anschließend muss eine dauerhafte Benachrichtigung erscheinen.

7. Vorhandene YAML-Bausteine verschieben

Verschiebe immer nur eine zusammengehörige Funktion und prüfe danach erneut. Eine Paketdatei für eine Waschküche könnte zum Beispiel so aufgebaut sein:

input_boolean:
  waschmaschine_laeuft:
    name: Waschmaschine läuft

template:
  - binary_sensor:
      - name: Waschmaschine aktiv
        unique_id: waschmaschine_aktiv_package
        state: "{{ is_state('input_boolean.waschmaschine_laeuft', 'on') }}"

automation:
  - alias: "Waschmaschine fertig melden"
    id: waschmaschine_fertig_melden_package
    triggers:
      - trigger: state
        entity_id: binary_sensor.waschmaschine_aktiv
        from: "on"
        to: "off"
    actions:
      - action: persistent_notification.create
        data:
          title: "Waschmaschine"
          message: "Die Waschmaschine ist fertig."

Das Beispiel zeigt nur die Struktur. Passe Namen und Logik erst an deine tatsächlichen Entitäten an. Verschiebe einen Block aus configuration.yaml erst dann, wenn du ihn in der Paketdatei eingefügt hast; derselbe Schlüssel oder dieselbe Automation darf nicht doppelt vorhanden sein.

Eindeutige Schlüssel und IDs

Helfer-Schlüssel wie waschmaschine_laeuft und Automations-IDs müssen in der gesamten Konfiguration eindeutig sein. Doppelte Einträge können das Zusammenführen der Packages verhindern oder zu unerwartetem Verhalten führen.

8. Ungeeignete Einträge in der Hauptdatei lassen

Die Authentifizierungsanbieter unter auth_providers müssen in configuration.yaml bleiben. Home Assistant verarbeitet sie vor den Packages. Verschiebe diese Einstellungen nicht:

homeassistant:
  auth_providers:
    - type: homeassistant

Auch UI-verwaltete Integrationen musst du nicht in Packages nachbauen. Packages sind vor allem für eigene YAML-Konfigurationen sinnvoll.

9. Typische Fehler beheben

Bei duplicate key existiert ein YAML-Schlüssel doppelt. Prüfe zuerst, ob du homeassistant: zweimal angelegt oder einen Helfer sowohl in der Hauptdatei als auch im Paket definiert hast.

Bei not a directory oder could not find expected kontrollierst du Ordnername, Dateiendung und Einrückung:

find packages -type f -name '*.yaml' -print

Der Befehl wird im Home-Assistant-Konfigurationsordner ausgeführt und listet alle geladenen Paketdateien auf.

Für den sicheren Rückweg entfernst du die Zeile packages: !include_dir_named packages aus configuration.yaml, stellst verschobene Blöcke aus dem Backup wieder her, prüfst die Konfiguration und startest erst dann neu.

Nicht mit fehlerhafter YAML neu starten

Eine unvollständige oder falsch eingerückte Datei kann den Start verhindern. Behalte das vollständige Backup, bis alle Pakete nach mehreren Neustarts fehlerfrei geladen werden.

10. Quellen und Stand

Die Syntax wurde am 27. August 2026 mit der offiziellen Home-Assistant-Dokumentation abgeglichen:

• Home Assistant: Configuration packages
• Home Assistant: Konfiguration auf mehrere Dateien aufteilen
• Home Assistant: Konfiguration prüfen und Fehler beheben

Fertig

Home Assistant lädt jetzt jede YAML-Datei im Ordner packages als eigenständiges Paket. Die Funktionsprüfung ist erfolgreich, wenn der Helfer Testlicht aktiv sichtbar ist und beim Einschalten die Benachrichtigung Package funktioniert erscheint.