Home Assistant YAML & Konfiguration
Home Assistant YAML lernen: Syntax verstehen, configuration.yaml beherrschen, Template-Sensoren erstellen und Jinja2-Templates nutzen.
Was ist YAML?
YAML (YAML Ain't Markup Language) ist ein einfaches Textformat für Konfigurationen. Es nutzt Einrückungen statt Klammern und ist damit sehr gut lesbar. Home Assistant verwendet YAML für alles, was nicht (oder noch nicht) über die UI konfigurierbar ist. Falls du YAML zum ersten Mal siehst: Keine Sorge, die Grundlagen sind in 10 Minuten gelernt.
Die 5 goldenen YAML-Regeln
- Einrückung mit Leerzeichen (2 Leerzeichen empfohlen, KEINE Tabs!)
- Schlüssel: Wert: immer mit Doppelpunkt und Leerzeichen
- Listen beginnen mit
-(Bindestrich + Leerzeichen) - Kommentare beginnen mit
# - Strings mit Sonderzeichen immer in Anführungszeichen
1# YAML Grundlagen: alle Konzepte
2# Das ist ein Kommentar
3
4# ── Einfacher Schlüssel-Wert ──
5name: "Mein Zuhause"
6elevation: 250
7debug_mode: true # Boolean: true/false
8
9# ── Verschachtelung (Einrückung!) ──
10location:
11 latitude: 52.52
12 longitude: 13.405
13 timezone: "Europe/Berlin"
14
15# ── Einfache Liste ──
16rooms:
17 - Wohnzimmer
18 - Küche
19 - Bad
20 - Schlafzimmer
21
22# ── Liste mit Objekten ──
23lights:
24 - name: Deckenlampe
25 type: dimmbar
26 room: Wohnzimmer
27 - name: Stehlampe
28 type: farbe
29 room: Schlafzimmer
30
31# ── Mehrzeiliger String (>) ──
32description: >
33 Dieser Text wird zu einer
34 einzigen Zeile zusammengefügt.
35
36# ── Mehrzeiliger String mit Zeilenumbrüchen (|) ──
37notes: |
38 Zeile 1 bleibt erhalten.
39 Zeile 2 auch.
40
41# ── Inline-Liste ──
42weekdays: [mon, tue, wed, thu, fri]
43
44# ── Inline-Objekt ──
45server: {host: "192.168.1.1", port: 8123}Merkhilfe: Der Unterschied zwischen
>und|: Das Größer-Zeichen faltet Zeilen zusammen (→ eine Zeile), der Strich bewahrt Zeilenumbrüche.
configuration.yaml
Die zentrale Konfigurationsdatei liegt unter /config/configuration.yaml.
Hier definierst du Einstellungen, die nicht über die UI konfigurierbar sind.
1# configuration.yaml: kommentiertes Beispiel
2# ── Grundeinstellungen ──
3homeassistant:
4 name: "Wohnung Berlin" # Name deines Zuhauses
5 unit_system: metric # Metrisches System
6 currency: EUR # Währung
7 country: DE # Land (ISO 3166)
8
9# ── Standardmäßig eingebaut ──
10default_config: # Lädt alle Standard-Integrationen
11
12# ── HTTP-Server Konfiguration ──
13http:
14 use_x_forwarded_for: true # Nötig hinter Reverse Proxy
15 trusted_proxies:
16 - 172.16.0.0/12 # Docker-Netzwerk
17 ip_ban_enabled: true # IP nach Fehlversuchen sperren
18 login_attempts_threshold: 5 # Nach 5 Fehlversuchen
19
20# ── Recorder-Einstellungen ──
21recorder:
22 purge_keep_days: 7 # Verlaufsdaten 7 Tage behalten
23 exclude:
24 domains:
25 - media_player
26 - weather
27 entity_globs:
28 - sensor.sun_*
29
30# ── Logger-Einstellungen ──
31logger:
32 default: warning # Standard-Level
33 logs:
34 homeassistant.components.mqtt: debug
35 custom_components: info
36
37# ── Eigene Template-Sensoren ──
38template:
39 - sensor:
40 - name: "Durchschnittstemperatur"
41 unit_of_measurement: "°C"
42 state: >
43 {{ ((states('sensor.wohnzimmer_temp') | float(0)) +
44 (states('sensor.schlafzimmer_temp') | float(0))) / 2 | round(1) }}
45
46# ── Dateien aufteilen ──
47automation: !include automations.yaml
48scene: !include scenes.yaml
49script: !include scripts.yamlDateien aufteilen mit !include
Bei wachsender Konfiguration wird die configuration.yaml schnell unübersichtlich.
Mit !include kannst du sie in mehrere Dateien aufteilen:
| Syntax | Beschreibung | Beispiel |
|---|---|---|
!include datei.yaml | Lädt eine einzelne Datei | automation: !include automations.yaml |
!include_dir_list ordner/ | Lädt alle Dateien als Liste | automation: !include_dir_list automations/ |
!include_dir_merge_list ordner/ | Lädt und merged Listen | Mehrere Dateien mit jeweils einer Liste |
!include_dir_named ordner/ | Dateiname wird Schlüssel | Ordner mit sensor/temp.yaml etc. |
1# Aufgeteilte Konfiguration
2# configuration.yaml:
3automation: !include_dir_merge_list automations/
4
5# Dann erstellst du separate Dateien:
6---
7# automations/licht.yaml:
8- alias: "Flur-Licht bei Bewegung"
9 trigger: ...
10 action: ...
11
12---
13# automations/heizung.yaml:
14- alias: "Heizung morgens"
15 trigger: ...
16 action: ...secrets.yaml
Sensible Daten wie Passwörter und API-Keys sollten NICHT direkt in der configuration.yaml stehen.
Stattdessen nutzt du secrets.yaml:
1# secrets.yaml
2# Passwörter und API-Keys hier speichern:
3mqtt_password: "mein-sicheres-passwort"
4openweather_api: "abc123def456"
5telegram_token: "bot123:ABC-DEF"
6latitude: "52.52"
7longitude: "13.405"# Verwendung in configuration.yaml
mqtt:
broker: 192.168.1.100
username: homeassistant
password: !secret mqtt_password # ← Liest aus secrets.yamlTipp: Wenn du deine HA-Konfiguration mit Git versionierst, füge
secrets.yamlzur.gitignorehinzu. So landen deine Passwörter nie im Repository.
YAML vs. UI-Konfiguration
| Aspekt | UI | YAML |
|---|---|---|
| Einfachheit | Klicken und auswählen | Text schreiben |
| Flexibilität | Begrenzt | Alles möglich |
| Versionierung | Schwer nachvollziehbar | Git-freundlich |
| Backup | In HA-Backup enthalten | Einfach als Textdatei |
| Template-Sensoren | Seit 2023 auch per UI | Immer möglich |
| Portabilität | An Installation gebunden | Einfach übertragbar |
| Massenbearbeitung | Einzeln | Suchen & Ersetzen |
Empfehlung: Starte mit der UI! Du kannst jederzeit zu YAML wechseln, wenn die UI an ihre Grenzen stößt. Viele Automationen zeigen dir in der UI den YAML-Code an, so lernst du nebenbei.
Häufige YAML-Fehler
| Fehler | Problem | Lösung |
|---|---|---|
| Tabs statt Leerzeichen | YAML erlaubt keine Tabs | Nutze 2 Leerzeichen. Stelle den Editor auf „Spaces" ein. |
| Fehlende Einrückung | Untergeordnete Elemente müssen eingerückt sein | Jede Ebene = 2 zusätzliche Leerzeichen |
: ohne Leerzeichen | name:wert statt name: wert | Immer Leerzeichen nach dem Doppelpunkt |
| Anführungszeichen vergessen | Strings mit :, #, {} etc. | In Anführungszeichen setzen: "Wert: mit Doppelpunkt" |
| Falsche Einrückungs-Ebene | Element auf falscher Ebene | Genau prüfen, zu welchem übergeordneten Element es gehört |
| Doppelte Schlüssel | Gleicher Schlüssel zweimal | Jeden Schlüssel nur einmal pro Ebene |
Tipp: Nutze den „Konfiguration prüfen"-Button unter Entwicklerwerkzeuge → YAML! Er zeigt dir genau die Zeile des Fehlers an.
Template-Sensoren (Jinja2)
Home Assistant nutzt Jinja2 als Template-Sprache. Damit kannst du berechnete Werte erstellen, dynamische Texte in Automationen schreiben und eigene Sensoren definieren.
Jinja2 Grundlagen
1# Jinja2 Syntax
2# ── Werte ausgeben ──
3{{ states('sensor.temperatur') }} # → "21.5"
4{{ state_attr('light.wohnzimmer', 'brightness') }} # → 200
5
6# ── Rechnen ──
7{{ states('sensor.temperatur') | float + 2 }} # → 23.5
8{{ states('sensor.preis') | float * 100 | round(2) }}
9
10# ── Bedingungen ──
11{{ "warm" if states('sensor.temp') | float > 25 else "kühl" }}
12
13# ── Filter ──
14{{ states('sensor.name') | upper }} # → "WOHNZIMMER"
15{{ states('sensor.name') | replace('_', ' ') }}
16{{ 1234.5 | round(0) }} # → 1235
17
18# ── Datum & Zeit ──
19{{ now().strftime('%H:%M') }} # → "14:30"
20{{ as_timestamp(now()) | timestamp_custom('%d.%m.%Y') }}
21
22# ── Listen filtern ──
23{{ states.light
24 | selectattr('state', 'eq', 'on')
25 | list | count }} # → Anzahl eingeschalteter LichterNeu in 2026.4: Neue Template-Funktionen
1# Neue Template-Funktionen (ab 2026.4)
2
3# state_attr_translated(): Gibt übersetzte Attributwerte zurück
4# Praktisch für Lüftermodi, HVAC-Aktionen, Preset-Modi etc.
5{{ state_attr_translated('climate.wohnzimmer', 'hvac_action') }}
6# → "Heizen" (statt "heating")
7
8{{ state_attr_translated('fan.ventilator', 'preset_mode') }}
9# → "Automatisch" (statt "auto")
10
11# entity_name(): Gibt den Anzeigenamen einer Entity zurück
12{{ entity_name('sensor.wohnzimmer_multisensor_temperatur') }}
13# → "Wohnzimmer Multisensor Temperatur"
14
15# Nützlich in Benachrichtigungen:
16# message: "{{ entity_name(trigger.entity_id) }} hat sich geändert"Template-Sensor Beispiele
1# Praktische Template-Sensoren
2template:
3 - sensor:
4 # ── Fenster-Zähler ──
5 - name: "Offene Fenster"
6 icon: mdi:window-open
7 state: >
8 {{ states.binary_sensor
9 | selectattr('attributes.device_class', 'eq', 'window')
10 | selectattr('state', 'eq', 'on')
11 | list | count }}
12
13 # ── Wer ist zuhause? ──
14 - name: "Personen zuhause"
15 icon: mdi:account-group
16 state: >
17 {{ states.person
18 | selectattr('state', 'eq', 'home')
19 | map(attribute='name')
20 | list | join(', ') or 'Niemand' }}
21
22 # ── Durchschnittstemperatur ──
23 - name: "Durchschnitt Innen"
24 unit_of_measurement: "°C"
25 device_class: temperature
26 state: >
27 {% set temps = [
28 states('sensor.wohnzimmer_temp') | float(0),
29 states('sensor.schlafzimmer_temp') | float(0),
30 states('sensor.kueche_temp') | float(0)
31 ] | reject('equalto', 0) | list %}
32 {{ (temps | sum / temps | count) | round(1) if temps else 'unavailable' }}
33
34 # ── Tägliche Stromkosten ──
35 - name: "Stromkosten heute"
36 unit_of_measurement: "€"
37 icon: mdi:currency-eur
38 state: >
39 {{ (states('sensor.strom_taeglich') | float(0) * 0.35) | round(2) }}
40
41 # ── Müll-Erinnerung ──
42 - name: "Nächste Abholung"
43 icon: mdi:trash-can
44 state: >
45 {% set events = state_attr('calendar.abfallkalender', 'description') %}
46 {{ events or 'Unbekannt' }}
47
48 # ── Binary Sensor (Ja/Nein) ──
49 - binary_sensor:
50 - name: "Jemand zuhause"
51 device_class: presence
52 state: >
53 {{ states.person
54 | selectattr('state', 'eq', 'home')
55 | list | count > 0 }}
56
57 - name: "Alle Fenster zu"
58 device_class: window
59 state: >
60 {{ states.binary_sensor
61 | selectattr('attributes.device_class', 'eq', 'window')
62 | selectattr('state', 'eq', 'on')
63 | list | count == 0 }}Packages: Alles zu einem Thema in einer Datei
Das Problem mit !include
Der klassische Ansatz mit !include teilt nach Domain auf: alle Automationen in eine Datei, alle Sensoren in eine andere, alle Input-Helfer in eine dritte. Das funktioniert, aber wenn du deine Waschmaschine ändern willst, springst du zwischen 5 Dateien hin und her.
1# Klassisch: nach Domain aufgeteilt
2config/
3├── configuration.yaml
4├── automations.yaml ← Heizung + Licht + Waschmaschine gemischt
5├── sensors.yaml ← Heizung + Licht + Waschmaschine gemischt
6└── input_booleans.yaml ← Heizung + Licht + Waschmaschine gemischtDie Lösung: Packages
Packages drehen die Logik um. Du teilst nach Thema auf. Alles was zur Waschmaschine gehört, lebt in einer einzigen Datei: Sensoren, Automationen, Helfer, Scripts. Das ist übersichtlicher und einfacher zu pflegen.
1# Mit Packages: nach Thema aufgeteilt
2config/
3├── configuration.yaml
4└── packages/
5 ├── heizung.yaml ← Alles zur Heizung
6 ├── waschmaschine.yaml ← Alles zur Waschmaschine
7 └── licht.yaml ← Alles zum LichtIn einem Package stehen ganz normal die gleichen Keys wie in der configuration.yaml. Hier ein Beispiel:
1# packages/waschmaschine.yaml - ALLES zur Waschmaschine an einem Ort
2
3template:
4 - sensor:
5 - name: "Waschmaschine Status"
6 state: >
7 {% set power = states('sensor.waschmaschine_power') | float(0) %}
8 {% if power > 1000 %}Waschen
9 {% elif power > 5 %}Laufen
10 {% elif power > 0 %}Standby
11 {% else %}Aus{% endif %}
12
13automation:
14 - alias: "Waschmaschine fertig"
15 trigger:
16 - platform: state
17 entity_id: sensor.waschmaschine_status
18 from: "Waschen"
19 to: "Standby"
20 for: "00:02:00"
21 action:
22 - service: notify.mobile_app_mein_handy
23 data:
24 title: "Waschmaschine fertig!"
25 message: "Die Wäsche kann aufgehängt werden."
26
27input_boolean:
28 waschmaschine_benachrichtigt:
29 name: "Waschmaschine bereits benachrichtigt"Packages einbinden: Drei Wege
Es gibt mehrere Wege, Packages in die configuration.yaml einzubinden. Welchen du wählst, hängt davon ab, wie viel Kontrolle du brauchst.
Weg 1: Einzeln per !include (volle Kontrolle)
Du bindest jedes Package einzeln ein und gibst ihm einen Namen:
1# configuration.yaml
2homeassistant:
3 packages:
4 waschmaschine: !include packages/waschmaschine.yaml
5 heizung: !include packages/heizung.yaml
6 licht: !include packages/licht.yamlVorteil: Du siehst sofort, welche Packages geladen werden, und kannst einzelne schnell auskommentieren. Nachteil: Jedes neue Package muss manuell eingetragen werden.
Weg 2: Ganzen Ordner automatisch laden (empfohlen)
Der einfachste Weg: Home Assistant lädt automatisch alle YAML-Dateien aus dem packages/-Ordner. Der Dateiname wird zum Package-Namen.
# configuration.yaml
homeassistant:
packages: !include_dir_named packagesDas war's. Wenn du eine neue Datei in packages/ anlegst, wird sie beim nächsten Neustart automatisch geladen. Kein Eintrag in der configuration.yaml nötig.
Vorteil: Neue Packages anlegen = Datei erstellen, fertig. Kein Vergessen, kein Nachtragen.
Nachteil: Weniger Kontrolle. Wenn du ein Package temporär deaktivieren willst, musst du die Datei umbenennen (z.B. waschmaschine.yaml.disabled).
Weg 3: Unterordner mit eigenen Package-Namen
Wenn du Packages in Unterordnern organisieren willst, nutze !include_dir_merge_named:
# configuration.yaml
homeassistant:
packages: !include_dir_merge_named packages/Der Unterschied: Hier definierst du den Package-Namen in der Datei selbst, nicht über den Dateinamen. Das erlaubt eine Ordnerstruktur mit Unterordnern:
1packages/
2├── heizung/
3│ ├── steuerung.yaml
4│ └── sensoren.yaml
5└── licht/
6 └── wohnzimmer.yamlJede Datei braucht dann den Package-Namen als obersten Key:
1# packages/heizung/steuerung.yaml
2heizung_steuerung:
3 automation:
4 - alias: "Heizung bei Abwesenheit drosseln"
5 trigger:
6 - platform: state
7 entity_id: binary_sensor.jemand_zuhause
8 to: "off"
9 action:
10 - service: climate.set_temperature
11 target:
12 entity_id: climate.wohnzimmer
13 data:
14 temperature: 17Dieser Weg lohnt sich erst bei sehr vielen Packages. Für die meisten Setups ist Weg 2 die beste Wahl.
Wie HA Packages zusammenführt
Wenn mehrere Packages (oder ein Package und die configuration.yaml) den gleichen Key verwenden, gelten folgende Regeln:
- Listen werden zusammengeführt: Wenn
heizung.yamlundlicht.yamlbeideautomation:definieren, sammelt HA alle Automationen ein. Das funktioniert genauso fürtemplate:,script:und andere listenbasierte Domains. - Entity-Keys müssen eindeutig sein: Bei
input_boolean:,input_number:und ähnlichen Domains darf jeder Entity-Key (z.B.heizung_auto) nur einmal vorkommen, egal ob in einem Package oder in derconfiguration.yaml. - Plattform-Integrationen mergen immer:
light:,switch:,sensor:mit Plattform-Konfiguration können problemlos in mehreren Packages gleichzeitig definiert werden.
Was nicht in Packages gehört
auth_providersmuss in derconfiguration.yamlbleiben. HA verarbeitet Auth-Provider beim Start, bevor Packages geladen werden.- Dateien, die der UI-Editor erwartet:
automations.yaml,scripts.yamlundscenes.yamlwerden vom UI-Editor direkt geschrieben. Wenn du Automationen auch über die UI anlegst, behalteautomation: !include automations.yamlin derconfiguration.yamlund nutze Packages nur für deine manuell geschriebenen YAML-Automationen.
Meine Empfehlung
Ich nutze Packages für alles, was zu einem Gerät oder Thema gehört. Die configuration.yaml bleibt schlank:
1# configuration.yaml - schlank und übersichtlich
2homeassistant:
3 packages: !include_dir_named packages
4
5# UI-Editor-Dateien bleiben separat
6automation: !include automations.yaml
7script: !include scripts.yaml
8scene: !include scenes.yamlDamit hast du das Beste aus beiden Welten: Packages für deine YAML-Konfiguration, und die Standard-Dateien für alles, was du über die UI anlegst.
Interaktiv ausprobieren
Willst du sehen, wie das alles in der Praxis zusammenspielt? Im Config Explorer klickst du dich durch eine echte Konfiguration mit klickbaren !include-Links, Package-Navigation und Erklärungen zu jeder Zeile.
Nützliche YAML-Patterns
Anchors & Aliases (Wiederverwendung)
1# YAML Anchors
2# Definiere einen Wert einmal mit &name
3defaults: &light_defaults
4 brightness_pct: 80
5 color_temp_kelvin: 3000
6 transition: 2
7
8# Verwende ihn mit *name
9automation:
10 - alias: "Licht Wohnzimmer"
11 action:
12 - service: light.turn_on
13 target:
14 entity_id: light.wohnzimmer
15 data:
16 <<: *light_defaults # ← Fügt alle Werte ein!
17
18 - alias: "Licht Schlafzimmer"
19 action:
20 - service: light.turn_on
21 target:
22 entity_id: light.schlafzimmer
23 data:
24 <<: *light_defaults # ← Gleiche Werte!
25 brightness_pct: 40 # ← Überschreibt nur diesen WertBedingte Konfiguration mit Template
1# Dynamische Werte in Automationen
2automation:
3 - alias: "Adaptive Helligkeit"
4 trigger:
5 - platform: state
6 entity_id: binary_sensor.flur_motion
7 to: "on"
8 action:
9 - service: light.turn_on
10 target:
11 entity_id: light.flur
12 data:
13 brightness_pct: >
14 {% if now().hour < 7 %}
15 20
16 {% elif now().hour < 18 %}
17 100
18 {% else %}
19 60
20 {% endif %}
21 color_temp_kelvin: >
22 {% if now().hour < 7 or now().hour > 20 %}
23 2700
24 {% else %}
25 4500
26 {% endif %}Konfiguration prüfen & validieren
Bevor du Home Assistant neustartest, immer die Konfiguration prüfen:
- Gehe zu Entwicklerwerkzeuge → YAML
- Klicke auf „Konfiguration prüfen"
- Wenn „Konfiguration ist gültig" erscheint → Neustart sicher
- Bei Fehlern: Die Fehlermeldung zeigt Dateiname und Zeilennummer
Profi-Tipp: Installiere das File Editor Add-on - es hat Syntax-Highlighting und zeigt YAML-Fehler direkt an. Alternativ: VS Code mit der Home Assistant Config Helper Extension für Auto-Completion und Validierung auf deinem PC.
Du kannst dein YAML auch direkt im Browser prüfen: Unser YAML Validator erkennt Syntaxfehler, falsche Einrückungen und Tippfehler sofort und bietet Auto-Fix. Und mit dem Template Tester kannst du Jinja2-Templates live ausprobieren, bevor du sie in deine Konfiguration einbaust.
Häufige Fragen
Wo finde ich die configuration.yaml?
Die Datei liegt im Config-Ordner deiner Installation, der vollständige Pfad ist /config/configuration.yaml. Am einfachsten bearbeitest du sie mit dem File Editor Add-on direkt in Home Assistant. Alternativ greifst du vom PC aus per Samba oder mit VS Code darauf zu.
Was sind Packages in Home Assistant?
Packages bündeln alles zu einem Thema in einer Datei: Sensoren, Automationen, Helfer und Scripts für die Waschmaschine landen zum Beispiel komplett in packages/waschmaschine.yaml. Statt nach Domain teilst du deine Konfiguration also nach Thema auf. Eingebunden werden Packages in der configuration.yaml unter homeassistant: packages, am einfachsten mit !include_dir_named.
Was bedeutet !include in Home Assistant?
Mit !include lagerst du Teile der configuration.yaml in separate Dateien aus, zum Beispiel automation: !include automations.yaml. Für ganze Ordner gibt es die Varianten !include_dir_list, !include_dir_merge_list und !include_dir_named. So bleibt deine Konfiguration auch bei vielen Automationen übersichtlich.
Wie prüfe ich meine YAML-Konfiguration auf Fehler?
Geh zu Entwicklerwerkzeuge, YAML und klicke auf Konfiguration prüfen. Bei Fehlern zeigt dir Home Assistant Dateiname und Zeilennummer an, erst bei „Konfiguration ist gültig" solltest du neustarten. Syntaxfehler findest du auch direkt im Browser mit dem YAML Validator.
Was ist ein Template-Sensor?
Ein Template-Sensor berechnet seinen Wert aus anderen Entities, mit der Template-Sprache Jinja2. Damit baust du zum Beispiel eine Durchschnittstemperatur aus mehreren Räumen, einen Zähler für offene Fenster oder die täglichen Stromkosten. Du definierst Template-Sensoren in der configuration.yaml unter template: oder seit 2023 auch über die UI.
Weiter lesen:
Passende Videos
Strompreisprognose in Home Assistant mit energyforecast.de
Ich zeige dir, wie du energyforecast.de über das EPEX-Spot-Plugin in Home Assistant einbindest und Verbraucher automatisch in günstige Stromstunden legst.
myUplink Integration: Wärmepumpe in Home Assistant
Mit der myUplink-Integration holst du jeden Sensor deiner Wärmepumpe in Home Assistant – inklusive echtem COP, Verbrauch und Schreibzugriff. Einrichtung in unter 10 Minuten.
Bubble Card für Home Assistant: alle Card-Typen erklärt
Bubble Card macht aus dem Standard-Lovelace ein modernes Dashboard mit Pop-Ups, Sub-Buttons und eigenem Styling. Ich zeige dir jeden Card-Typ mit YAML.
