How to Edit Configuration YAML in Home Assistant

Introduction

Home Assistant uses YAML files for configuration. The main configuration file is configuration.yaml, located in your Home Assistant config directory. This guide covers how to safely edit this file and validate changes.

Finding the Configuration File

The location depends on your Home Assistant installation type:

Home Assistant OS / Supervised

/config/configuration.yaml

Docker Installation

~/homeassistant/configuration.yaml
# or wherever you mounted the config volume

Python Virtual Environment

~/.homeassistant/configuration.yaml

Methods to Edit Configuration

Method 1: File Editor Add-on (Recommended)

Use the built-in File Editor add-on for safe editing:

Go to Settings → Add-ons → File editor
Open the add-on and navigate to configuration.yaml
Make your edits
Click "Save"
Validate configuration in Developer Tools → YAML

Method 2: SSH Access

Edit via SSH using a text editor:

# Connect via SSH
ssh root@homeassistant.local

# Edit with nano
nano /config/configuration.yaml

# Or with vi
vi /config/configuration.yaml

Method 3: Samba Share

Access files via network share:

Enable Samba add-on in Home Assistant
Map network drive on your computer
Open configuration.yaml with your preferred editor
Save and validate in Home Assistant

Basic Configuration Structure

A typical configuration.yaml file structure:

# Home Assistant configuration.yaml

# Basic information
homeassistant:
  name: Home
  latitude: 40.7128
  longitude: -74.0060
  elevation: 10
  unit_system: imperial
  time_zone: America/New_York

# HTTP configuration
http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 127.0.0.1
    - ::1

# Logging
logger:
  default: info
  logs:
    homeassistant.components.sensor: debug

# Automation
automation: !include automations.yaml

# Script
script: !include scripts.yaml

# Scene
scene: !include scenes.yaml

Common Configuration Edits

Adding a New Integration

Example: Adding MQTT broker configuration:

mqtt:
  broker: 192.168.1.100
  port: 1883
  username: mqtt_user
  password: mqtt_password

Configuring Sensors

Example: Adding a sensor:

sensor:
  - platform: template
    sensors:
      temperature:
        friendly_name: "Temperature"
        value_template: "{{ states('sensor.weather_temperature') }}"

Setting Up Automations

Example: Basic automation structure:

automation:
  - alias: "Turn on lights at sunset"
    trigger:
      - platform: sun
        event: sunset
    action:
      - service: light.turn_on
        target:
          entity_id: light.living_room

Validating Configuration

Always validate your YAML before restarting Home Assistant:

Method 1: Developer Tools

Go to Developer Tools → YAML
Click "Check Configuration"
Review any errors or warnings

Method 2: Command Line

# SSH into Home Assistant
ssh root@homeassistant.local

# Validate configuration
ha core check

Method 3: Online Validator

Use YAML.cc validator to check syntax before applying changes:

Copy your YAML content
Paste into YAML validator
Fix any syntax errors
Copy back to Home Assistant

Best Practices

•
Always backup before editing - Create a backup of configuration.yaml before making changes
•
Validate before restarting - Use Developer Tools to check configuration before restarting
•
Use includes for organization - Split large configurations into separate files using !include
•
Test changes incrementally - Make small changes and test before adding more
•
Use comments - Add comments to document your configuration choices

Common Errors and Fixes

Error: Invalid YAML

Caused by incorrect indentation or syntax:

# Check indentation (use 2 spaces)
# Ensure colons have spaces after them
# Quote strings with special characters

Error: Integration not found

Verify integration name and configuration format:

# Check Home Assistant documentation
# Verify integration is installed
# Ensure correct platform name