Configuration Guide

Learn how to configure Home Assistant Core, including configuration.yaml structure and using configuration constants.

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

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):

1. Navigate to Settings → Devices & Services
2. Click Add Integration
3. Search for and select the integration
4. 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:

1. Command Line Check

   hass --script check_config --config /path/to/config
   
2. Developer Tools

   Navigate to Developer Tools → YAML → Check Configuration

3. 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).

Next Steps

Developer Docs

Explore the full developer documentation

Integration Development

Learn to create custom integrations

Configuration Reference

Complete configuration reference

Community Forum

Get help from the community

Additional Resources

• Configuration.yaml Examples
• YAML Syntax Guide
• Secrets Documentation
• Splitting Configuration