YAML hat einen unverdient schlechten Ruf. Viele Einsteiger schieben den Blick in die Konfigurationsdateien monatelang vor sich her, dabei ist YAML eine der einfachsten Auszeichnungssprachen überhaupt. Vier Regeln, mehr brauchst du nicht. Und sobald sie sitzen, kannst du jedes Beispiel aus Foren und Blogs lesen, anpassen und in dein Setup übernehmen.
Was YAML eigentlich ist: eine strukturierte, lesbare Art, Daten aufzuschreiben. Maschinen können sie verstehen, Menschen können sie trotzdem flüssig lesen. Du erkennst die Dateien an der Endung .yaml, das ist einfach ein Dateiformat wie .jpg für Bilder. Im Video gehe ich die Regeln an echten Home-Assistant-Beispielen durch. Hier die Kurzfassung zum Nachlesen.
Regel 1: Alles ist Schlüssel und Wert
Die Grundeinheit von YAML ist das Paar aus Schlüssel, Doppelpunkt und Wert. name: Wohnzimmer heißt: Der Schlüssel name hat den Wert Wohnzimmer. Das war's. Eine ganze Konfiguration ist nichts anderes als viele solcher Paare, ineinander verschachtelt.
Werte können Text sein, Zahlen oder Wahrheitswerte. Eine Eigenheit solltest du kennen: on und off ohne Anführungszeichen interpretiert YAML als wahr und falsch. Wenn du den Zustand eines Schalters meinst, schreib "on" mit Anführungszeichen. Dieser eine Stolperstein verursacht erstaunlich viele Support-Fragen.
Ein komplettes Beispiel mit lauter Schlüssel-Wert-Paaren, ein Eingabefeld-Helfer für die Laufkilometer des Monats:
1input_number:
2 laufband_kilometer:
3 name: "Kilometer diesen Monat"
4 min: 0
5 max: 500
6 step: 1
7 unit_of_measurement: "km"Lies es einmal laut: Es gibt Input-Number-Helfer, darin einen mit der ID laufband_kilometer, und der hat einen Namen, ein Minimum, ein Maximum. Genau so liest du jede YAML-Datei, Ebene für Ebene.
Regel 2: Einrückung ist Struktur
Was in anderen Formaten Klammern erledigen, macht in YAML die Einrückung. Wer JSON kennt: Dort öffnest du geschweifte Klammern, um ein Objekt in ein anderes zu packen. YAML rückt stattdessen ein. Zwei Leerzeichen weiter rechts heißt: Das hier gehört zum Schlüssel darüber. Das siehst du auch im Beispiel oben, die ID gehört zu input_number:, die Eigenschaften gehören zur ID.
1automation:
2 - alias: "Licht an bei Bewegung" # Element einer Liste
3 trigger: # gehört zur Automation
4 - platform: state # gehört zu trigger
5 entity_id: binary_sensor.flur
6 to: "on"
7 action:
8 - service: light.turn_on
9 target:
10 entity_id: light.flurZwei Dinge sind dabei nicht verhandelbar. Erstens: immer Leerzeichen, niemals Tabs. Tabs sind in YAML schlicht verboten und der häufigste Grund für kryptische Fehlermeldungen. Das Fiese daran: Im Editor sehen Tab und Leerzeichen erstmal gleich aus. In Editoren mit sichtbaren Leerzeichen erkennst du den Unterschied, ein Tab erscheint dort als ein breites Zeichen, Leerzeichen als einzelne Punkte. Zweitens: Konsistenz. Home Assistant verwendet überall zwei Leerzeichen pro Ebene, bleib dabei.
Regel 3: Listen beginnen mit Bindestrich
Sobald mehrere gleichartige Dinge aufeinander folgen, kommt die Liste ins Spiel. Jedes Element beginnt mit einem Bindestrich auf gleicher Höhe. Im Beispiel oben ist automation: eine Liste von Automationen und trigger: eine Liste von Auslösern, auch wenn beide nur ein Element haben. Deshalb der Bindestrich.
Regel 4: Kommentare mit Raute
Alles hinter einem # ignoriert Home Assistant. Nutze das großzügig. Ein # Schaltet nachts auf 10% statt 100% über einer Zeile erklärt dir in einem halben Jahr, warum du das so gebaut hast.
Anführungszeichen: wann ja, wann nein
Diese Frage kommt verlässlich, deshalb hier die ehrliche Antwort: YAML ist da nicht ganz konsequent. Bei einfachen Werten wie name: Wohnzimmer sind Anführungszeichen optional, du kannst sie setzen oder weglassen, es macht keinen Unterschied. Verpflichtend werden sie in drei Fällen: bei "on" und "off", wenn du wirklich den Text meinst, bei Werten mit Doppelpunkt im Text und bei Jinja-Templates, die mit {{ beginnen. Mein pragmatischer Rat: Im Zweifel setz sie. Schaden tun sie nie, fehlen kann teuer werden.
Die häufigsten Fehler und ihre Symptome
| Fehler | Typisches Symptom |
|---|---|
| Tab statt Leerzeichen | "found character that cannot start any token" |
| Eine Ebene falsch eingerückt | Schlüssel wird ignoriert oder "mapping values are not allowed" |
| Doppelpunkt im Text ohne Anführungszeichen | Fehlermeldung oder zerlegter Wert |
on/off ohne Anführungszeichen | Automation reagiert nie |
Gegen alle vier hilft dieselbe Routine: Nach jeder Änderung Entwicklerwerkzeuge → YAML → Konfiguration prüfen, erst dann neu laden. Erscheint die grüne Meldung, ist nichts in der Konfiguration, was Home Assistant am Hochfahren hindert, und du kannst bedenkenlos neu starten. Die Prüfung zeigt dir sonst Datei und Zeilennummer des Problems. Wenn du trotzdem feststeckst, hilft der Troubleshooting-Guide.
Der richtige Editor nimmt dir Arbeit ab
Du kannst YAML im einfachen File-Editor-Add-on bearbeiten, das reicht für den Anfang. Ich empfehle dir trotzdem das Studio-Code-Server-Add-on, und zwar aus handfesten Gründen: Es hebt die Syntax farbig hervor, markiert kaputte Stellen direkt beim Tippen, zeigt zusammengehörige Listenelemente an und lässt dich lange Blöcke einklappen. Falsche Einrückung oder ein Komma an der falschen Stelle siehst du dort, bevor du überhaupt speicherst.
Gerade die Tab-Falle aus Regel 2 entschärft der Editor fast von selbst, weil du eingestellte Tabs automatisch in zwei Leerzeichen umwandeln lassen kannst. Aus eigener Erfahrung: Die halbe Stunde Einrichtung spart dir später Stunden Fehlersuche.
YAML steckt überall in Home Assistant
Hier kommt der Punkt, der vielen nicht klar ist: YAML lebt nicht nur in der configuration.yaml. Der visuelle Automations-Editor hat eine YAML-Ansicht, ein Klick aufs Menü genügt, und du siehst deine geklickte Automation als Code. Das ist nicht nur zum Lernen gut. Logische Fehler findest du im Code oft schneller als im Klick-Editor, weil du alle Bedingungen untereinander siehst: Welche Conditions sind mit "oder" verknüpft, was passiert in welchem Zweig. Im Video lese ich so eine Automation einmal komplett durch, und genau dieses Durchsteppen kannst du mit jeder deiner eigenen machen.
Auch Dashboards haben einen YAML-Modus. Den brauchst du spätestens, wenn du Karten aus dem HACS-Store einbaust, denn manche davon lassen sich nur dort konfigurieren. Und in Template-Sensoren begegnen sich YAML und die Jinja-Templates: YAML beschreibt die Struktur des Sensors, das Template berechnet seinen Wert. Sieht auf den ersten Blick nach wildem Mix aus, folgt aber genau den vier Regeln von oben.
Brauchst du YAML überhaupt noch?
Berechtigte Frage, denn Automationen, Helfer und Dashboards lassen sich inzwischen komplett klicken. Meine Antwort: Du musst YAML nicht schreiben können, aber lesen. Die besten Lösungen für knifflige Probleme kursieren als YAML-Schnipsel in Foren und Blogs. Wer die vier Regeln kennt, kopiert sie nicht blind, sondern versteht und passt sie an.
Die YAML-Ansicht des Automations-Editors ist dafür der sanfteste Kurs, den es gibt, mit Beispielen aus deinem eigenen Setup. Und ein paar Dinge gehen weiterhin nur per Datei, etwa Template-Sensoren oder die Struktur der Konfiguration selbst.
Wie die Konfigurationsdateien zusammenspielen und wo welche Einstellung lebt, vertieft der YAML-Guide. Wenn du ganz am Anfang stehst, lies vorher den Erster-Start-Guide.
Häufige Fragen
Muss ich YAML lernen, um Home Assistant zu nutzen?
Nein, die alltäglichen Dinge wie Automationen, Helfer und Dashboards klickst du komplett in der Oberfläche zusammen. YAML lesen zu können lohnt sich trotzdem, weil die besten Lösungen aus Foren und Blogs als YAML-Schnipsel geteilt werden. Schreiben lernst du dann nebenbei, wenn du es brauchst.
Warum bekomme ich nach einer Änderung eine Fehlermeldung?
In neun von zehn Fällen ist es die Einrückung: ein Tab statt Leerzeichen oder eine Ebene zu viel beziehungsweise zu wenig. Die Konfigurationsprüfung unter Entwicklerwerkzeuge → YAML nennt dir Datei und Zeilennummer. Schau dir die Zeile und die direkt darüber an, dort sitzt der Fehler fast immer.
Was passiert, wenn meine Konfiguration kaputt ist und ich neu starte?
Deshalb gibt es die Prüfung vor dem Neustart: Konfiguration prüfen, auf die grüne Meldung warten, erst dann neu laden. Startest du mit einem schweren Fehler neu, kann Home Assistant im abgesicherten Modus hochfahren, in dem Teile der Konfiguration fehlen. Mit der Prüf-Routine passiert dir das nicht.
Welchen Editor soll ich für YAML benutzen?
Für den Einstieg reicht das File-Editor-Add-on. Sobald du regelmäßig in den Dateien arbeitest, wechsle zum Studio-Code-Server-Add-on: Syntax-Hervorhebung, Fehlerwarnungen beim Tippen und automatische Einrückung nehmen dir die typischen YAML-Fehler ab, bevor sie entstehen.
