2026 edition — revised for Home Assistant’s 2026 documentation and terminology.

Based on SIYTEK’s original 2023 handbook and the unpublished 2024 draft. Technical review: November 2026.

YAML has a reputation for being intimidating. A misplaced space can break a configuration, and a few lines of YAML can look like a foreign language if you don’t know what the punctuation means. I’ve been there too. The good news is that YAML has a small set of underlying rules, and once you understand them, Home Assistant configuration becomes much easier to read.

This free guide starts with those rules and works through scenes, scripts, automations, and ways to organise a growing configuration. Each Home Assistant example identifies the file it belongs in, and you’ll learn how to check your work rather than just hoping that a pasted example works.

Who this is for: Home Assistant users who are comfortable navigating the interface but want to understand and safely edit YAML. You don’t need programming experience.

Before you start: Back up Home Assistant. The entity IDs in the examples (such as light.living_room_lamp_1) are illustrative; replace them with entities that exist in your installation. The examples use current Home Assistant conventions, but some UI labels and integration options can change between releases.

Contents

  1. What is YAML?
  2. YAML syntax without the guesswork
  3. Where YAML fits into Home Assistant
  4. Edit configuration safely
  5. Build your first scene
  6. Create scripts in YAML
  7. Write automations in YAML
  8. Split up configuration files
  9. Variables, secrets, and templates
  10. Troubleshooting and a practical checklist

What is YAML?

YAML stands for YAML Ain’t Markup Language. It’s a human-readable format for storing structured information, frequently used for application configuration. A YAML document describes data: names, values, lists, and relationships between them. YAML isn’t a programming language and doesn’t execute instructions by itself. Home Assistant reads YAML and interprets its contents according to the integration or feature being configured.

Here is a YAML representation of a little shop:

shop:
  bakery:
    - bread
    - cake
  cafe:
    - tea
    - coffee

The shop contains two named categories; each category contains a list. That is essentially all the magic: indentation shows which values belong to which other values.

You will often see filenames ending in .yaml or .yml. Home Assistant predominantly uses .yaml; follow the application’s documented filenames. A leading --- is an optional YAML document-start marker, not a required first line for Home Assistant configuration. A final newline is good editing practice, but not a Home Assistant-specific requirement.

YAML syntax without the guesswork

Mappings: keys and values

A mapping, sometimes called a dictionary, associates a key with a value:

name: "Alex"
age: 30
location: "Kitchen"

Here name, age, and location are keys. The colon separates each key from its value. A space after the colon is important. Indent child keys beneath their parent:

person:
  name: "Alex"
  address:
    city: "Cheltenham"
    country: "United Kingdom"

city belongs to address, which belongs to person. The indent does not have to be precisely two spaces in every YAML file, but it must be consistent at each level. Two spaces per level is an easy convention to follow. Use spaces rather than tab characters for indentation.

Important: a mapping should not define the same key twice. Duplicating scene: at the same level, for example, is an error or can produce unexpectedly overwritten data, depending on the parser. We will look at Home Assistant’s labelled integration sections later.

Sequences: lists of items

A sequence, or list, begins each item with a dash and a space:

rooms:
  - kitchen
  - living_room
  - bedroom

List items can contain mappings of their own:

lights:
  - name: "Desk lamp"
    room: "Office"
  - name: "Ceiling light"
    room: "Living room"

Notice that name and room line up within each item. When you later create a list of automations, the same principle applies: each automation starts with a -, and its own properties are nested beneath it.

Strings, numbers, booleans, and quotation marks

Values can be text, numbers, booleans (true or false), lists, or nested mappings. Quotation marks matter when you need a specific value to stay text, especially when punctuation or words resembling booleans appear.

title: "Evening routine"
wait_seconds: 30
enabled: true
state: "on"
start_time: "07:30:00"

30 is a number; "30" is text. In Home Assistant, state names such as "on" and "off" are safest written as strings. Quoting time values prevents unexpected interpretation. In an automation’s to: or from: field, use the exact state string shown by Home Assistant rather than guessing.

Use a folded block (>) for a long message that can be joined onto one logical line, and a literal block (|) when line breaks are significant:

summary: >
  This sentence can be written over
  several source lines.

message: |
  First line
  Second line

Comments and whitespace

A # begins a comment when it appears in a suitable YAML position. Comments explain why a configuration exists; they do not affect the configuration itself:

# Keep the hallway light on while leaving home.
hallway_delay_seconds: 120  # Two minutes

YAML has no separate multiline-comment syntax; use # on each comment line. Leave a space before an inline comment for readability. Don’t over-comment obvious syntax: describe the intent of a rule or a surprising decision instead.

A complete example you can read

users:
  - name: "Alex"
    username: "alex123"
    hobbies:
      - electronics
      - home automation
  - name: "Jamie"
    username: "jamie456"
    hobbies:
      - gardening
      - photography

Ask yourself: How many users are there? Which hobby belongs to which user? If you can answer both, you already understand the structure used by many Home Assistant YAML examples.

Where YAML fits into Home Assistant

Home Assistant uses YAML for certain configuration files and advanced configuration options, but most routine setup can now be performed through its user interface. Adding a device, creating a basic automation, or configuring many integrations normally does not require opening configuration.yaml.

Learning YAML is still useful when you want to understand an exported automation, use advanced features, control configuration in files, or organise a large installation. It is also handy when adapting examples from the documentation — provided you check that the syntax is still current.

Installation type matters

Home Assistant Operating System (OS) and Home Assistant Container are not the same thing:

  • Home Assistant OS provides a managed system with apps. You can install the File editor app from Settings → Apps or use Studio Code Server. Its configuration is conventionally accessible as /config.
  • Home Assistant Container does not have Home Assistant’s app store. Edit the host directory mounted into the container as its configuration volume. The host path is whatever you selected when setting up Docker.

Don’t rely on a generic path such as ~/.homeassistant for every Raspberry Pi, Mac, Debian, or Windows installation. To check your installation type and system details, go to Settings → System → Repairs, open the three-dot menu (⋮) in the top-right corner, and select System information. For a Container installation, inspect the volume mapping to identify the actual host configuration directory. This is more reliable than a platform-based list of historical paths.

The configuration directory

A typical configuration might contain these files:

config/
├── configuration.yaml
├── automations.yaml
├── scripts.yaml
├── scenes.yaml
├── secrets.yaml
├── themes/
└── custom_components/

Your installation may have additional or different files. Edit the configuration directory, not the Home Assistant application or Python installation files. The latter are managed by Home Assistant or your installation method.

The main file, configuration.yaml, often includes entries like these:

# configuration.yaml — representative structure, not a replacement file
default_config:

# Keep the UI-managed files connected.
automation: !include automations.yaml
script: !include scripts.yaml
scene: !include scenes.yaml

!include tells Home Assistant to load the contents of a different file as the value of that key. The included file does not repeat the parent key. For example, scenes.yaml contains a list of scenes, not another scene: heading.

Don’t overwrite your own configuration.yaml with this illustration. Your real file may contain settings that are essential to your installation.

Edit configuration safely

Prepare an editor

On Home Assistant OS, open Settings → Apps, install the File editor app if it isn’t already installed, and start it. Optionally enable its sidebar entry for convenient access. On Home Assistant Container, use an editor on the host system where the configuration volume is mounted. In either case, use an editor that shows spaces and provides syntax highlighting.

If your UI looks different from the accompanying screenshots in older SIYTEK articles, consult the current official configuration guide. The Home Assistant interface and its terminology have changed since the original 2023 edition.

Protect a working installation

Before experimenting, create a backup appropriate to your installation. For Home Assistant OS, use its built-in backup facilities. If your installation is containerised, back up the actual configuration volume and any separately persisted data according to your deployment. Keep a recoverable copy off the device as well.

Make one small change at a time. If you have a working automation created with the UI, don’t remove the original automation: !include automations.yaml line just to experiment with hand-written automation YAML. We will add a separate, labelled section instead.

Validate, reload, then test

After saving a configuration change:

  1. Use Settings → Tools → YAML → Check configuration, when available, to check the full Home Assistant configuration.
  2. Fix any reported errors, including missing files, duplicate keys, invalid integration options and indentation mistakes.
  3. Reload the relevant YAML configuration from Settings → Tools → YAML, or use Settings → System → Quick reload. Some changes, including adding an integration for the first time, require a Home Assistant restart.
  4. Check that the intended entities exist and behave as expected. A successful syntax check is not proof that an automation will do the right thing.

Unlike a simple YAML parser, Home Assistant validates the configuration against its own integration schemas. Both checks matter. A YAML document can be syntactically valid but use a key in the wrong place.

Build your first scene

A scene describes the desired states of one or more entities. For example, you might want two lights at a particular brightness or several lights switched off. Scenes do not have their own triggers; you activate a scene manually or from a script or automation.

The original SIYTEK guide used this lesson to explain YAML lists, and it remains a great first Home Assistant example.

Keep UI-created scenes intact

Home Assistant scenes created in the editor are stored in scenes.yaml. You can create a scene with the visual editor and inspect its YAML, which is an excellent way to learn. For a separate hand-written scene file, you can keep that UI-managed file and add a labelled scene integration in configuration.yaml:

# configuration.yaml — keep your existing scene include
scene: !include scenes.yaml

# Add a separate YAML-managed set of scenes
scene manual: !include scenes_manual.yaml

Create scenes_manual.yaml in the configuration directory with the following contents. Don’t paste another scene: key into the included file:

# scenes_manual.yaml
- id: "siytek_relax_living_room"
  name: "Relax Living Room"
  entities:
    light.living_room_lamp_1:
      state: "on"
      brightness: 77
    light.living_room_lamp_2:
      state: "off"

- id: "siytek_living_room_off"
  name: "Living Room Off"
  entities:
    light.living_room_lamp_1:
      state: "off"
    light.living_room_lamp_2:
      state: "off"

The first scene turns one lamp on to approximately 30% brightness (77 out of 255) and switches another off. The second turns both off. Replace the example entity IDs with real ones from Settings → Tools → States.

Why brightness: 77, not brightness_pct: 30? A scene stores an entity state and its attributes. The light’s stored brightness attribute uses a scale from 0 to 255. In contrast, the light.turn_on action accepts brightness_pct. Mixing the two can result in a scene that doesn’t set the brightness you intended.

Check the configuration, reload scenes, then find the new scene entity under Settings → Tools → States or in the Scenes interface. An entity might be named scene.relax_living_room, but confirm its actual ID rather than assuming it from the title.

Activate a scene

Use the UI’s action tester, or invoke the equivalent YAML from a script:

- action: scene.turn_on
  target:
    entity_id: scene.relax_living_room

This is an action snippet, not a whole configuration.yaml file. The leading dash means it belongs in a list of actions or script sequence. Again, substitute the scene entity ID from your installation.

Scenes are not scripts

A scene sets a desired collection of states; it doesn’t execute a timed sequence. If you need to turn off one set of lights, wait two minutes, and then switch off the hallway light, you need a script.

Create scripts in YAML

A script is a sequence of actions that runs when you start it — from the dashboard, another script, an automation, or the action tester. Unlike an automation, it has no trigger of its own.

The original ebook taught a useful leaving-home example: switch off the living-room lights, keep the hallway illuminated briefly, then turn it off. Let’s build that again with modern action syntax.

Keep the script editor working

Home Assistant keeps scripts created in its visual editor in scripts.yaml. Preserve that file and its include. Add a second labelled section for hand-written scripts:

# configuration.yaml
script: !include scripts.yaml
script manual: !include scripts_manual.yaml

Now create scripts_manual.yaml. This is a mapping: the script name is the key, so it does not begin with a list dash.

# scripts_manual.yaml
lightsout:
  alias: "Lights out, hallway last"
  description: "Turn off living-room lights, then the hallway after a delay"
  mode: restart
  sequence:
    - alias: "Turn off the living-room lights"
      action: light.turn_off
      target:
        entity_id:
          - light.living_room_lamp_1
          - light.living_room_lamp_2

    - alias: "Allow time to leave"
      delay: "00:02:00"

    - alias: "Turn off the hallway light"
      action: light.turn_off
      target:
        entity_id: light.hallway

Here, lightsout is a script key; Home Assistant normally exposes it as script.lightsout. The sequence is a YAML list, so each action begins with a dash. The steps execute in order. mode: restart means a fresh invocation restarts the sequence if it is still running — useful for this particular delay, although another mode might suit another script.

You can run the script from Settings → Automations & scenes → Scripts or call script.lightsout from an automation. Confirm the script’s actual entity ID and test it with harmless lights before connecting it to anything safety-critical.

Reuse a scene inside a script

If you created the “Living Room Off” scene in the previous chapter, replace the first light-off step with:

- action: scene.turn_on
  target:
    entity_id: scene.living_room_off

This keeps the desired light states in one reusable scene. It also demonstrates the difference between storing a state (scene) and running actions (script).

Allow a variable delay

A script can accept inputs. The following alternative version shows the relevant fields and templated delay; don’t create another lightsout key alongside the earlier version unless you intend to replace it.

# scripts_manual.yaml — alternative version
lightsout:
  alias: "Lights out, hallway last"
  mode: restart
  fields:
    minutes:
      name: "Hallway delay"
      description: "How long to leave the hallway lit"
      default: 2
      selector:
        number:
          min: 0
          max: 10
          step: 1
          unit_of_measurement: minutes
  sequence:
    - action: light.turn_off
      target:
        entity_id:
          - light.living_room_lamp_1
          - light.living_room_lamp_2
    - delay:
        minutes: "{{ minutes | default(2) | int }}"
    - action: light.turn_off
      target:
        entity_id: light.hallway

The fields declaration describes an input shown in the editor. The template supplies a fallback of two minutes when the caller doesn’t provide one. After reloading scripts, use the script’s run interface to try a short delay before deploying the routine.

Write automations in YAML

An automation has triggers, optional conditions, and actions:

  • A trigger says when Home Assistant should evaluate the automation.
  • A condition says whether it should continue at that moment.
  • An action says what should happen.

The distinction matters. A trigger notices that a lamp changed to "on"; a condition can check whether it’s dark; an action turns on the other lights.

Current syntax versus older guides

Older Home Assistant examples — including the original SIYTEK edition — frequently use the singular top-level trigger:, condition:, action: fields, platform: for a trigger type, and service: for an action call. They remain recognisable, but Home Assistant’s current style is:

triggers:
  - trigger: state
    entity_id: light.living_room_lamp_1
    to: "on"
conditions: []
actions:
  - action: light.turn_on
    target:
      entity_id: light.living_room_lamp_2

This is one automation’s content. The outer YAML list dash is added when it lives in a file containing several automations. Do not mix the old and new names for the same key in the same location.

Example 1: turn on a lamp at sunset

Preserve your UI automations and add a labelled manual section in configuration.yaml:

# configuration.yaml
# Keep the normal UI-managed file.
automation: !include automations.yaml

# Add an independent file for hand-written automations.
automation manual: !include automations_manual.yaml

Then create automations_manual.yaml. Because the integration expects a list, the automation begins with -:

# automations_manual.yaml
- id: "siytek_sunset_lamp"
  alias: "Turn on living-room lamp at sunset"
  description: "Switch on one lamp when the sun sets"
  triggers:
    - trigger: sun.sunset
  conditions: []
  actions:
    - action: light.turn_on
      target:
        entity_id: light.living_room_lamp_1
      data:
        brightness_pct: 40
  mode: single

Here the sunset trigger starts the automation at sunset. This uses the newer trigger: sun.sunset form. You may also encounter the supported older form, trigger: sun with event: sunset, in existing automations and tutorials. The action calls light.turn_on, which accepts brightness_pct. You can omit the empty conditions: [] field; I’ve included it so the three main parts are easy to identify.

Because we supplied an id, the automation can retain its identity and benefit from traces. Reload automations, then use the automation’s Run actions facility to test the action. Be aware that manually running actions does not prove that the sunset trigger will fire — trigger and condition behaviour must be tested separately.

Example 2: turn on other lights only after dark

This time the main lamp turning on is the trigger. The sun being below the horizon is the condition:

# Another item in automations_manual.yaml
- id: "siytek_lights_after_dark"
  alias: "Bring on the other lamps after dark"
  triggers:
    - trigger: state
      entity_id: light.living_room_lamp_1
      to: "on"
  conditions:
    - condition: state
      entity_id: sun.sun
      state: "below_horizon"
  actions:
    - action: light.turn_on
      target:
        entity_id:
          - light.living_room_lamp_2
          - light.living_room_lamp_3
  mode: single

What happens? When lamp 1 turns on, Home Assistant checks sun.sun. If the sun is below the horizon, lamps 2 and 3 turn on. If not, nothing happens. The condition is checked at trigger time; the automation doesn’t wait for sunset to become true later.

Example 3: call the hallway-delay script

An automation can also start the script from our previous chapter. For example, a helper switch could initiate the leaving-home routine:

# Another item in automations_manual.yaml
- id: "siytek_leaving_home"
  alias: "Run lights-out routine"
  triggers:
    - trigger: state
      entity_id: input_boolean.leaving_home
      to: "on"
  actions:
    - action: script.lightsout
      data:
        minutes: 2
  mode: single

This assumes you’ve separately created an input_boolean.leaving_home helper. It’s intentionally a testable, explicit trigger; you can create the helper through the UI and toggle it to run the automation. It does not infer your presence or automatically unlock doors.

Testing and traces

If an automation doesn’t run, confirm its trigger’s entity ID and actual state, its enabled state, and whether its conditions are true. Review its trace and logs rather than adding arbitrary delays. A manual “Run actions” test typically bypasses trigger/condition evaluation; it only tells you whether the action sequence can execute. Read the official automation testing guide.

Split up configuration files

As your YAML collection grows, keeping everything in one file becomes inconvenient. This was one of the strongest sections of the original ebook, and the key distinction is still list versus mapping.

A single include

Suppose configuration.yaml contains:

script manual: !include scripts_manual.yaml

script expects a mapping. The included file contains only keys such as lightsout: and their definitions; it must not start with another script: key and does not need to be indented to match its caller.

Similarly:

automation manual: !include automations_manual.yaml

expects a list of automations, each beginning with -.

Split lists across a directory

For multiple hand-written automations, create a directory:

config/
├── configuration.yaml
├── automations.yaml             # UI-managed; keep intact
└── automations_manual/
    ├── sunset.yaml
    └── lights_after_dark.yaml

Then in configuration.yaml:

automation: !include automations.yaml
automation manual: !include_dir_merge_list automations_manual/

Each file in automations_manual/ contains a YAML list. For example, sunset.yaml starts with - id: "siytek_sunset_lamp", followed by its triggers and actions. !include_dir_merge_list combines the lists into one automation collection.

You can use the same principle with scene files:

scene: !include scenes.yaml
scene manual: !include_dir_merge_list scenes_manual/

Each file in scenes_manual/ must contain a list, even when it contains just one scene.

Merge mappings across a directory

Scripts are mappings rather than lists. Create files such as:

config/
├── configuration.yaml
├── scripts.yaml                 # UI-managed; keep intact
└── scripts_manual/
    ├── lightsout.yaml
    └── movie_time.yaml

Use:

script: !include scripts.yaml
script manual: !include_dir_merge_named scripts_manual/

Each file contains a mapping whose top-level key is the script name:

# scripts_manual/lightsout.yaml
lightsout:
  alias: "Lights out"
  sequence:
    - action: light.turn_off
      target:
        entity_id: light.hallway

!include_dir_merge_named merges dictionaries. Don’t put a script: parent into the included file, and don’t reuse the same script key across two files.

A subtle detail: directory include helpers scan .yaml files; .yml files are not included by those helpers. Use .yaml for the directory-based examples in this guide.

Which include should I use?

Include directive Result Typical use
!include file.yaml The contents of one file Scripts, scenes, or automations in a single file
!include_dir_merge_list folder/ One combined sequence Multiple automation or scene files
!include_dir_merge_named folder/ One combined mapping Multiple script files or named configuration entries
!include_dir_list folder/ A list with each file as an item A specialised use where each file represents one list item
!include_dir_named folder/ Mapping keyed by filename Configurations requiring named sections

Use the directive that matches the structure expected at that location. Loading valid YAML of the wrong shape is still an integration configuration error.

Packages: an alternative organisation style

Once you’re comfortable with separate files, consider Home Assistant packages. Packages group different integration settings by a feature or room, rather than by integration type. They have their own include rules and merging behaviour, so don’t convert an existing setup without reading the documentation and making a backup first.

Variables, secrets, and templates

These concepts go beyond the first edition but are worth learning because they appear in real configurations.

Define variables for reusable values

A variable gives a value a name so that later steps in the same script or automation run can use it. For example, these are two actions inside a script’s sequence: or an automation’s actions: list:

# Example actions within a script or automation
- variables:
    evening_brightness: 40

- action: light.turn_on
  target:
    entity_id: light.living_room_lamp_1
  data:
    brightness_pct: "{{ evening_brightness }}"

The first step defines evening_brightness; the second uses a Jinja template to pass its value to light.turn_on. Change the value in one place to adjust the action. Here brightness_pct means 40%, because it is a light action parameter, not an attribute stored in a scene. This variables: action makes the value available to later steps in the run; it does not permanently create a Home Assistant entity or store a value across runs. For more on variable scope, see Define variables.

Never publish credentials in YAML examples

Keep API keys, passwords and access tokens out of articles and public repositories. Home Assistant supports the !secret tag, which looks up a value from secrets.yaml:

# Example fragment within an integration that expects an API key
api_key: !secret example_api_key
# secrets.yaml — illustrative value only
example_api_key: "replace-me-with-a-private-value"

secrets.yaml avoids copying secrets into other configuration files, but it is not encryption. Restrict access to it, protect backups, and never commit real credentials to a public repository.

Basic Home Assistant templates

Home Assistant uses Jinja templates to build values dynamically. For example, this expression reads an entity’s state:

{{ states('sensor.living_room_temperature') }}

states('...') is generally safer than directly navigating a nested state object because it can handle an entity being unavailable without raising the same lookup error. It still can return unknown or unavailable, so handle those cases when you need a number:

{{ states('sensor.living_room_temperature') | float(0) }}

Here 0 is a fallback, not a trustworthy replacement temperature. Do not use a default that could cause a safety-critical automation to make the wrong decision. Experiment with templates in Home Assistant’s template editor before using them in production.

Troubleshooting and a practical checklist

“My YAML won’t load”

Start with the basics: Are the indentation levels consistent? Is a list item missing its dash? Is a colon missing? Have you used tabs? Do quotation marks come in matching pairs? Did you add a second top-level scene: or script: key? Is the file you referenced with !include present under the exact name you typed?

Also check whether you wrote a list where Home Assistant expects a mapping. This example is valid YAML but the wrong shape if used as the content of a script include:

# Wrong shape for a script mapping
- lightsout:
    sequence: []

For a script include, the correct shape is a mapping:

# Correct shape for a script mapping
lightsout:
  sequence:
    - action: light.turn_off
      target:
        entity_id: light.hallway

“My scene exists but the brightness doesn’t change”

Check the scene entity’s stored attributes. A scene should use a light’s brightness attribute (0–255), not the brightness_pct action parameter. Confirm the light supports brightness control, reload the scene, then reactivate it. Remember that the editor can rewrite or remove comments in a UI-managed scene.

“My automation doesn’t trigger”

Look at the actual state in Settings → Tools → States. Entity IDs may not match their friendly names. Inspect the automation’s trace and confirm the trigger is enabled. If it has a to: "on" state trigger, it runs on the appropriate state change, not merely because the light is already on when Home Assistant starts.

“My UI-created scripts or automations disappeared”

Check whether you replaced automation: !include automations.yaml, script: !include scripts.yaml, or scene: !include scenes.yaml. Restore the original include, and use a separate labelled manual integration section as demonstrated above. This is precisely why the new examples do not teach readers to delete the UI-managed includes.

“My YAML passes the syntax check but nothing happens”

A general YAML parser checks structure, not whether Home Assistant has an entity named light.hallway. The Home Assistant configuration checker checks schemas, but it cannot guarantee a real device will respond. Check the entity in the UI, test the action directly, inspect logs and traces, and change one thing at a time.

Before you finish

  • Make a recoverable backup and know how to restore it.
  • Keep your UI-managed includes intact.
  • Replace every example entity ID with one from your own installation.
  • Check configuration, reload the relevant part, and test the effect.
  • Use current action and automation syntax for new work.
  • Keep secrets out of articles, repositories and screenshots.

Further reading

The best companion to this guide is the current official Home Assistant documentation:

What’s next?

Congratulations — you can now read a YAML mapping, recognise a list, write a scene, build a reusable script, create an automation and split a larger configuration into manageable files. More importantly, you know how to test those changes without sacrificing a working installation.

You do not have to write everything in YAML to get the most out of Home Assistant. Use the UI when it helps, use YAML when it gives you the control you need, and treat the two approaches as complementary. Keep experimenting in small, reversible steps.

Happy automating!