Configuration Guide - Home Assistant

Home Assistant Core uses YAML files for configuration, with configuration.yaml as the main configuration file. This guide covers configuration structure, options, and best practices.

Configuration Directory

Home Assistant stores all configuration in a dedicated directory:

Default: ~/.homeassistant (Linux/macOS)
Custom: Specify with hass --config /path/to/config

Configuration Files

~/.homeassistant/
├── configuration.yaml      # Main configuration
├── secrets.yaml           # Sensitive data
├── automations.yaml       # Automation definitions
├── scripts.yaml           # Script definitions  
├── scenes.yaml            # Scene definitions
├── groups.yaml            # Group definitions (optional)
└── customize.yaml         # Entity customizations (optional)

Home Assistant automatically creates default configuration files on first run using the template in homeassistant/config.py.

Main Configuration File

The configuration.yaml file is the entry point for all configuration.

Default Configuration

When Home Assistant starts for the first time, it creates this default configuration:

configuration.yaml

# Loads default set of integrations. Do not remove.
default_config:

# Load frontend themes from the themes folder
frontend:
  themes: !include_dir_merge_named themes

automation: !include automations.yaml
script: !include scripts.yaml
scene: !include scenes.yaml

The default_config integration loads a curated set of integrations that provide a great out-of-the-box experience. See the default_config documentation for details.

Core Configuration

The homeassistant: section configures core settings.

Basic Configuration

configuration.yaml

homeassistant:
  # Name of the location where Home Assistant is running
  name: Home
  
  # Location coordinates (for sun/weather calculations)
  latitude: 37.7749
  longitude: -122.4194
  
  # Altitude above sea level in meters
  elevation: 0
  
  # Unit system: 'metric' or 'imperial'
  unit_system: metric
  
  # Time zone (TZ database format)
  time_zone: America/Los_Angeles
  
  # Currency for financial data
  currency: USD
  
  # Country code (ISO 3166-1 alpha-2)
  country: US
  
  # Language code (ISO 639-1)
  language: en

URLs Configuration

configuration.yaml

homeassistant:
  # External URL (for external access)
  external_url: https://example.duckdns.org:8123
  
  # Internal URL (for local network access)
  internal_url: http://homeassistant.local:8123

The external_url should use HTTPS for security. Never expose Home Assistant over HTTP to the internet.

Allowlist Configuration

configuration.yaml

homeassistant:
  # Allow external files/iframes from these URLs
  allowlist_external_dirs:
    - /usr/share/hassio/homeassistant
    - /media
  
  allowlist_external_urls:
    - https://example.com

Media Directories

configuration.yaml

homeassistant:
  # Directories for media files
  media_dirs:
    local: /media
    nas: /mnt/nas/media

Configuration Constants

Home Assistant defines configuration constants in homeassistant/const.py. These provide consistent keys for configuration:

Common Configuration Keys

# From homeassistant/const.py
CONF_NAME: Final = "name"
CONF_HOST: Final = "host"
CONF_PORT: Final = "port"
CONF_USERNAME: Final = "username"
CONF_PASSWORD: Final = "password"
CONF_API_KEY: Final = "api_key"
CONF_ACCESS_TOKEN: Final = "access_token"
CONF_IP_ADDRESS: Final = "ip_address"
CONF_MAC: Final = "mac"
CONF_DEVICE_ID: Final = "device_id"

Entity Configuration Keys

CONF_ENTITY_ID: Final = "entity_id"
CONF_FRIENDLY_NAME: Final = "friendly_name"
CONF_DEVICE_CLASS: Final = "device_class"
CONF_ENTITY_CATEGORY: Final = "entity_category"
CONF_ICON: Final = "icon"
CONF_UNIT_OF_MEASUREMENT: Final = "unit_of_measurement"

Using Constants in Integrations

"""Example integration using constants."""
from homeassistant.const import (
    CONF_HOST,
    CONF_PORT,
    CONF_USERNAME,
    CONF_PASSWORD,
)
import voluptuous as vol

PLATFORM_SCHEMA = vol.Schema({
    vol.Required(CONF_HOST): str,
    vol.Optional(CONF_PORT, default=8080): int,
    vol.Required(CONF_USERNAME): str,
    vol.Required(CONF_PASSWORD): str,
})

Secrets Management

Store sensitive data in secrets.yaml to keep it separate from configuration.

secrets.yaml

# Passwords and tokens
http_password: your_secure_password
api_key_service: abc123xyz789
db_url: postgresql://user:pass@localhost/db

# Network credentials  
wifi_ssid: MyNetwork
wifi_password: MyPassword

Using Secrets

Reference secrets with the !secret tag:

configuration.yaml

http:
  api_password: !secret http_password

sensor:
  - platform: some_service
    api_key: !secret api_key_service

Never commit secrets.yaml to version control! Add it to .gitignore.

Splitting Configuration

For large configurations, split files using !include directives.

Include Single File

configuration.yaml

automation: !include automations.yaml
script: !include scripts.yaml
scene: !include scenes.yaml

Include Directory (List)

Load all YAML files from a directory as a list:

configuration.yaml

automation: !include_dir_list automations/

automations/
├── lights.yaml
├── climate.yaml
└── security.yaml

Include Directory (Merge List)

Merge lists from multiple files:

configuration.yaml

sensor: !include_dir_merge_list sensors/

Include Directory (Merge Named)

Create a dictionary from files (filename becomes key):

configuration.yaml

group: !include_dir_merge_named groups/

groups/
├── rooms.yaml        # Becomes group.rooms
└── devices.yaml      # Becomes group.devices

Integration Configuration

YAML-Based Integrations

Some integrations are configured via YAML:

configuration.yaml

# HTTP Server
http:
  server_port: 8123
  ssl_certificate: /ssl/fullchain.pem
  ssl_key: /ssl/privkey.pem
  cors_allowed_origins:
    - https://example.com

# Logging
logger:
  default: info
  logs:
    homeassistant.core: debug
    homeassistant.components.mqtt: warning

# Recorder (Database)
recorder:
  db_url: sqlite:///home-assistant_v2.db
  purge_keep_days: 7
  include:
    domains:
      - sensor
      - switch
      - light

# History
history:
  include:
    domains:
      - sensor
      - switch

UI-Based Integrations

Many modern integrations use the UI for configuration (Config Entries):

Navigate to Settings → Devices & Services
Click Add Integration
Search for and select the integration
Follow the configuration flow

Config Entry integrations are stored in .storage/core.config_entries (do not edit manually).

Customization

Customize entity attributes using the customize: section.

Basic Customization

configuration.yaml

homeassistant:
  customize:
    # Change entity name and icon
    light.living_room:
      friendly_name: Living Room Light
      icon: mdi:lightbulb
    
    # Hide entity from UI
    sensor.debug_sensor:
      hidden: true
    
    # Set device class
    binary_sensor.front_door:
      device_class: door

Customize by Domain

configuration.yaml

homeassistant:
  customize_domain:
    light:
      assumed_state: false

Customize by Pattern

configuration.yaml

homeassistant:
  customize_glob:
    "light.kitchen_*":
      icon: mdi:stove
    "sensor.*_temperature":
      device_class: temperature

Packages

Packages allow you to bundle related configuration:

configuration.yaml

homeassistant:
  packages:
    pack_1: !include packages/pack_1.yaml

packages/pack_1.yaml

# Complete configuration for a feature
automation:
  - alias: Package Automation
    trigger:
      - platform: state
        entity_id: binary_sensor.motion
    action:
      - service: light.turn_on
        target:
          entity_id: light.hallway

light:
  - platform: template
    lights:
      package_light:
        friendly_name: Package Light
        turn_on:
          service: script.turn_on_light
        turn_off:
          service: script.turn_off_light

Configuration Validation

Home Assistant validates configuration using Voluptuous schemas.

Schema Example

"""Example configuration schema."""
import voluptuous as vol
from homeassistant.const import CONF_HOST, CONF_PORT, CONF_NAME
import homeassistant.helpers.config_validation as cv

CONFIG_SCHEMA = vol.Schema({
    vol.Required(CONF_HOST): cv.string,
    vol.Optional(CONF_PORT, default=80): cv.port,
    vol.Optional(CONF_NAME): cv.string,
}, extra=vol.PREVENT_EXTRA)

Common Validators

From homeassistant.helpers.config_validation:

import homeassistant.helpers.config_validation as cv

# Basic types
cv.string
cv.boolean  
cv.positive_int
cv.positive_float

# Network
cv.port
cv.url
cv.matches_regex(r"^[a-z]+$")

# Time
cv.time_period
cv.time_zone

# Entity
cv.entity_id
cv.entity_domain("light")

# Service
cv.service

Checking Configuration

Validate configuration before restarting:

Command Line Check

hass --script check_config --config /path/to/config

Developer Tools

Navigate to Developer Tools → YAML → Check Configuration

Review Output

Look for errors or warnings in the output. Fix any issues before restarting.

Always check your configuration after making changes to avoid startup failures.

Safe Mode

If Home Assistant fails to start due to configuration errors, it can enter safe mode:

# Start in recovery mode
hass --recovery-mode --config /path/to/config

In safe mode:

Minimal integrations are loaded
Web UI is accessible
You can fix configuration issues
No automations run

Configuration File Locations

Finding Config Directory

# From homeassistant/config.py
def get_default_config_dir() -> str:
    """Get default configuration directory."""
    data_dir = os.path.expanduser("~")
    return os.path.join(data_dir, CONFIG_DIR_NAME)

CONFIG_DIR_NAME = .homeassistant
YAML_CONFIG_FILE = configuration.yaml
VERSION_FILE = .HA_VERSION

Alternative Locations

# Specify custom directory
hass --config /etc/homeassistant

# Current directory
hass --config ./config

# Absolute path
hass --config /home/user/ha-config

Environment-Specific Configuration

Use environment variables for deployment-specific settings:

configuration.yaml

homeassistant:
  latitude: !env_var HA_LATITUDE
  longitude: !env_var HA_LONGITUDE

http:
  server_port: !env_var HA_PORT 8123

# Set environment variables
export HA_LATITUDE=37.7749
export HA_LONGITUDE=-122.4194
export HA_PORT=8123

hass

Best Practices

Use Secrets

Always store passwords, API keys, and tokens in secrets.yaml, never in configuration.yaml.

Version Control

Keep configuration.yaml in Git, but exclude secrets.yaml and .storage/ directories.

Split Large Configs

Use !include directives to split large configurations into manageable files.

Check Before Restart

Always validate configuration with hass --script check_config before restarting.

Document Customizations

Add comments to explain complex configurations for future reference.

Backup Regularly

Back up your configuration directory regularly, especially before major changes.

Common Configuration Patterns

Template Sensors

configuration.yaml

template:
  - sensor:
      - name: "Living Room Temperature"
        unit_of_measurement: "°C"
        state: >
          {{ states('sensor.temperature_raw') | float * 0.1 }}

Input Helpers

configuration.yaml

input_boolean:
  guest_mode:
    name: Guest Mode
    icon: mdi:account-multiple

input_number:
  temperature_threshold:
    name: Temperature Threshold
    min: 15
    max: 30
    step: 0.5
    unit_of_measurement: "°C"

Groups

configuration.yaml

group:
  living_room:
    name: Living Room
    entities:
      - light.living_room_main
      - light.living_room_lamp
      - switch.tv

Troubleshooting

Configuration Errors

Error: “Invalid config for [domain]: …”Solution: Check the error message for details. Common issues include:

Missing required fields
Incorrect data types
Invalid entity IDs
Malformed YAML syntax

YAML Syntax Errors

# Validate YAML syntax
python3 -c "import yaml; yaml.safe_load(open('configuration.yaml'))"

Use 2 spaces for indentation in YAML files. Never use tabs.

Secrets Not Found

Error: “Secret [secret_name] not found”Solution: Ensure the secret exists in secrets.yaml and the name matches exactly (case-sensitive).

Getting Started

Core Architecture

Building Integrations

Core Concepts

Development

​Configuration Directory

​Configuration Files

​Main Configuration File

​Default Configuration

​Core Configuration

​Basic Configuration

​URLs Configuration

​Allowlist Configuration

​Media Directories

​Configuration Constants

​Common Configuration Keys

​Entity Configuration Keys

​Using Constants in Integrations

​Secrets Management

​secrets.yaml

​Using Secrets

​Splitting Configuration

​Include Single File

​Include Directory (List)

​Include Directory (Merge List)

​Include Directory (Merge Named)

​Integration Configuration

​YAML-Based Integrations

​UI-Based Integrations

​Customization

​Basic Customization

​Customize by Domain

​Customize by Pattern

​Packages

​Configuration Validation

​Schema Example

​Common Validators

​Checking Configuration

​Safe Mode

​Configuration File Locations

​Finding Config Directory

​Alternative Locations

​Environment-Specific Configuration

​Best Practices

Use Secrets

Version Control

Split Large Configs

Check Before Restart

Document Customizations

Backup Regularly

​Common Configuration Patterns

​Template Sensors

​Input Helpers

​Groups

​Troubleshooting

​Configuration Errors

​YAML Syntax Errors

​Secrets Not Found

​Next Steps

Developer Docs

Integration Development

Configuration Reference

Community Forum

​Additional Resources

Build docs developers (and LLMs) love

Configuration Directory

Configuration Files

Main Configuration File

Default Configuration

Core Configuration

Basic Configuration

URLs Configuration

Allowlist Configuration

Media Directories

Configuration Constants

Common Configuration Keys

Entity Configuration Keys

Using Constants in Integrations

Secrets Management

secrets.yaml

Using Secrets

Splitting Configuration

Include Single File

Include Directory (List)

Include Directory (Merge List)

Include Directory (Merge Named)

Integration Configuration

YAML-Based Integrations

UI-Based Integrations

Customization

Basic Customization

Customize by Domain

Customize by Pattern

Packages

Configuration Validation

Schema Example

Common Validators

Checking Configuration

Safe Mode

Configuration File Locations

Finding Config Directory

Alternative Locations

Environment-Specific Configuration

Best Practices

Common Configuration Patterns

Template Sensors

Input Helpers

Groups

Troubleshooting

Configuration Errors

YAML Syntax Errors

Secrets Not Found

Next Steps

Additional Resources