What config.txt actually is and why you need to edit it

Configuration.yaml is the main settings file that tells Home Assistant how to work. It controls which devices Home Assistant can see, how automations behave, which integrations load, and dozens of other settings. When you want Home Assistant to do something it doesn't do by default — add a new device, change how a sensor reports data, or set up an automation — you usually edit this file.

Home Assistant reads configuration.yaml every time it starts up. If the file has a mistake in it, Home Assistant won't start, and you'll see an error message. That's why editing it carefully matters: a single misplaced space or missing colon can break everything.

The file lives in your Home Assistant config folder. On most setups, that's at /config/configuration.yaml. You can't edit it by opening it in Notepad on your computer — you need to use Home Assistant's built-in editor or SSH into the machine running Home Assistant.

Key Takeaways

  • Configuration.yaml is a plain-text file that controls how Home Assistant works, and mistakes in it will prevent Home Assistant from starting.
  • The easiest way to edit it is through Home Assistant's web interface using the File Editor add-on, which checks your work before you save.
  • YAML formatting is strict: indentation must use spaces (not tabs), colons and dashes must be in the right places, and quotes matter.
  • Always make a backup of your configuration.yaml before editing, and restart Home Assistant after you save changes.
  • If Home Assistant won't start after an edit, you can revert to your backup or use SSH to fix the file from the command line.

Using the File Editor add-on through the web interface

The simplest way to edit configuration.yaml is through Home Assistant's web interface. Go to Settings (the gear icon in the bottom left), then Add-ons, then Add-on Store. Search for File Editor and install it. Once installed, click Start, then check the box for Show in sidebar.

The File Editor will now appear in your sidebar. Click it, and you'll see a file browser on the left. Navigate to configuration.yaml and click it to open. The editor will show the file's contents on the right side. Make your changes, then click the checkmark icon at the top right to validate the file. If there's a YAML error, the editor will tell you where it is. Once validation passes, click the save icon (the floppy disk) to save.

After you save, go back to Settings > System > Restart to restart Home Assistant. It will read the new configuration.yaml and apply your changes. This usually takes 30 seconds to a few minutes depending on how many integrations you have.

Understanding YAML formatting rules

Configuration.yaml uses a format called YAML, which is strict about spacing and punctuation. The most common mistakes are indentation errors, missing colons, and using tabs instead of spaces.

Indentation in YAML must use spaces, never tabs. Each level of indentation is usually 2 spaces. If you have a line that starts with a dash (like - platform: mqtt), the dash counts as the first character, and the next line at the same level should also start with a dash. Lines nested under that line should be indented 2 more spaces.

Here's what correct YAML looks like:

automation: !include automations.yaml sensor:   - platform: template     sensors:       living_room_temp:         value_template: "{{ states('sensor.living_room') }}"

Notice that each nested level is indented 2 more spaces, colons come after the key name, and the dash is followed by a space. The File Editor will highlight syntax errors in red, so use that as your guide.

Making a backup before you edit

Before you make any changes to configuration.yaml, make a copy. In the File Editor, right-click on configuration.yaml and select Copy. Then right-click in the empty space below and select Paste. Rename the copy to something like configuration.yaml.backup or configuration.yaml.old.

If something goes wrong after your edit and Home Assistant won't start, you can use SSH to delete the broken file and rename the backup back to configuration.yaml. This takes less than a minute and will get you running again while you figure out what went wrong.

You can also export your entire Home Assistant configuration from Settings > System > Backups. A full backup includes configuration.yaml plus all your automations, scripts, and other settings. Keep one of these somewhere safe — on a USB drive or cloud storage — so you can restore everything if your Home Assistant machine fails.

Editing via SSH if the web interface isn't available

If Home Assistant won't start or the web interface is unreachable, you can edit configuration.yaml using SSH. You'll need SSH enabled on your Home Assistant machine. Go to Settings > System > SSH & Web Terminal and turn on the SSH server (if it's not already on).

On Windows, use a tool like PuTTY or Windows Terminal. On Mac or Linux, open Terminal. Connect with ssh root@homeassistant.local (or replace homeassistant.local with your Home Assistant machine's IP address). You'll be prompted for a password — use the same password you use to log into Home Assistant's web interface.

Once connected, type nano /config/configuration.yaml to open the file in the nano editor. Make your changes, then press Ctrl+O to save, press Enter to confirm the filename, and press Ctrl+X to exit. Then type ha core restart to restart Home Assistant.

Common mistakes and how to fix them

The most frequent error is mixing tabs and spaces. If you copy and paste a configuration example from a website, it might contain tabs. The File Editor will show a red squiggle under the problem line. Delete the indentation and retype it using your spacebar, not Tab.

Another common mistake is forgetting the colon after a key. Every line that has a value should end with a colon, like sensor: or automation:. If you see an error pointing to the line after the one you edited, check the line above it for a missing colon.

Quotes around values matter in some cases. If a value starts with a number, a special character, or a colon, wrap it in quotes. For example, value: "123" or name: "My: Device". If you're not sure, quotes don't hurt.

If Home Assistant starts but your new device or automation doesn't work, check the Settings > System > Logs page. Scroll to the bottom and look for error messages that mention the part of configuration.yaml you edited. The error message usually points to the exact line and problem.

When to use includes instead of editing the main file

As your configuration.yaml grows, it becomes harder to manage. Home Assistant lets you split it into separate files using the !include command. For example, at the top of configuration.yaml, you can write:

automation: !include automations.yaml script: !include scripts.yaml sensor: !include sensors.yaml

Then create separate files called automations.yaml, scripts.yaml, and sensors.yaml in the same folder. Each file contains only the configuration for that section. This makes it easier to find and edit specific parts without scrolling through a huge file.

You can also use !include_dir_list or !include_dir_merge_list to load multiple files from a folder. This is useful if you have many similar devices. For example, you could put each device's configuration in its own file inside a devices/ folder, and load them all at once.

Frequently Asked Questions

What happens if I restart Home Assistant while I'm editing configuration.yaml?

Home Assistant will try to start with the version of the file that was last saved. If you haven't saved your changes, they'll be lost. If you have saved but the file has an error, Home Assistant will fail to start and show an error message. Don't restart until you've finished editing and validated the file.

Can I edit configuration.yaml on my computer and upload it?

You can, but it's risky. If you edit it in Notepad or Word, the file might get corrupted or saved in the wrong format. Use a plain-text editor like VS Code or Sublime Text if you want to edit on your computer, then use the File Editor's upload feature or SSH to copy it over. The File Editor's built-in validation is safer because it checks your work before you save.

Why does Home Assistant say there's an error but I don't see one?

YAML errors are often on the line before the one Home Assistant reports. If the error message points to line 50, check lines 48 and 49 for missing colons, wrong indentation, or mismatched quotes. Also check that you're using spaces, not tabs, for indentation.

Can I revert to an older version of configuration.yaml?

If you made a backup before editing, you can rename the backup back to configuration.yaml and restart. If you didn't make a backup, you can restore from a full Home Assistant backup if you have one. Otherwise, you'll need to manually recreate the configuration or use SSH to edit the file and remove the problematic lines.

Do I need to restart Home Assistant every time I edit configuration.yaml?

Yes. Home Assistant only reads configuration.yaml when it starts up. Any changes you make won't take effect until you restart. Some add-ons and integrations can be reloaded without a full restart, but configuration.yaml changes always require a restart.