> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/home-assistant/core/llms.txt
> Use this file to discover all available pages before exploring further.

# 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)
```

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

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

```yaml configuration.yaml theme={null}
# 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
```

<Info>
  The `default_config` integration loads a curated set of integrations that provide a great out-of-the-box experience. See the [default\_config documentation](https://www.home-assistant.io/integrations/default_config/) for details.
</Info>

## Core Configuration

The `homeassistant:` section configures core settings.

### Basic Configuration

```yaml configuration.yaml theme={null}
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

```yaml configuration.yaml theme={null}
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
```

<Warning>
  The `external_url` should use HTTPS for security. Never expose Home Assistant over HTTP to the internet.
</Warning>

### Allowlist Configuration

```yaml configuration.yaml theme={null}
homeassistant:
  # Allow external files/iframes from these URLs
  allowlist_external_dirs:
    - /usr/share/hassio/homeassistant
    - /media
  
  allowlist_external_urls:
    - https://example.com
```

### Media Directories

```yaml configuration.yaml theme={null}
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

```python theme={null}
# 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

```python theme={null}
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

```python theme={null}
"""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

```yaml secrets.yaml theme={null}
# 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:

```yaml configuration.yaml theme={null}
http:
  api_password: !secret http_password

sensor:
  - platform: some_service
    api_key: !secret api_key_service
```

<Warning>
  **Never commit `secrets.yaml` to version control!** Add it to `.gitignore`.
</Warning>

## Splitting Configuration

For large configurations, split files using `!include` directives.

### Include Single File

```yaml configuration.yaml theme={null}
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:

```yaml configuration.yaml theme={null}
automation: !include_dir_list automations/
```

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

### Include Directory (Merge List)

Merge lists from multiple files:

```yaml configuration.yaml theme={null}
sensor: !include_dir_merge_list sensors/
```

### Include Directory (Merge Named)

Create a dictionary from files (filename becomes key):

```yaml configuration.yaml theme={null}
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:

```yaml configuration.yaml theme={null}
# 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

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

## Customization

Customize entity attributes using the `customize:` section.

### Basic Customization

```yaml configuration.yaml theme={null}
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

```yaml configuration.yaml theme={null}
homeassistant:
  customize_domain:
    light:
      assumed_state: false
```

### Customize by Pattern

```yaml configuration.yaml theme={null}
homeassistant:
  customize_glob:
    "light.kitchen_*":
      icon: mdi:stove
    "sensor.*_temperature":
      device_class: temperature
```

## Packages

Packages allow you to bundle related configuration:

```yaml configuration.yaml theme={null}
homeassistant:
  packages:
    pack_1: !include packages/pack_1.yaml
```

```yaml packages/pack_1.yaml theme={null}
# 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

```python theme={null}
"""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`:

```python theme={null}
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:

<Steps>
  <Step title="Command Line Check">
    ```bash theme={null}
    hass --script check_config --config /path/to/config
    ```
  </Step>

  <Step title="Developer Tools">
    Navigate to **Developer Tools** → **YAML** → **Check Configuration**
  </Step>

  <Step title="Review Output">
    Look for errors or warnings in the output. Fix any issues before restarting.
  </Step>
</Steps>

<Tip>
  Always check your configuration after making changes to avoid startup failures.
</Tip>

## Safe Mode

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

```bash theme={null}
# 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

```python theme={null}
# 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

```bash theme={null}
# 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:

```yaml configuration.yaml theme={null}
homeassistant:
  latitude: !env_var HA_LATITUDE
  longitude: !env_var HA_LONGITUDE

http:
  server_port: !env_var HA_PORT 8123
```

```bash theme={null}
# Set environment variables
export HA_LATITUDE=37.7749
export HA_LONGITUDE=-122.4194
export HA_PORT=8123

hass
```

## Best Practices

<Card title="Use Secrets" icon="lock">
  Always store passwords, API keys, and tokens in `secrets.yaml`, never in `configuration.yaml`.
</Card>

<Card title="Version Control" icon="code-branch">
  Keep `configuration.yaml` in Git, but exclude `secrets.yaml` and `.storage/` directories.
</Card>

<Card title="Split Large Configs" icon="folder-tree">
  Use `!include` directives to split large configurations into manageable files.
</Card>

<Card title="Check Before Restart" icon="check">
  Always validate configuration with `hass --script check_config` before restarting.
</Card>

<Card title="Document Customizations" icon="file-lines">
  Add comments to explain complex configurations for future reference.
</Card>

<Card title="Backup Regularly" icon="floppy-disk">
  Back up your configuration directory regularly, especially before major changes.
</Card>

## Common Configuration Patterns

### Template Sensors

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

### Input Helpers

```yaml configuration.yaml theme={null}
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

```yaml configuration.yaml theme={null}
group:
  living_room:
    name: Living Room
    entities:
      - light.living_room_main
      - light.living_room_lamp
      - switch.tv
```

## Troubleshooting

### Configuration Errors

<Warning>
  **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
</Warning>

### YAML Syntax Errors

```bash theme={null}
# Validate YAML syntax
python3 -c "import yaml; yaml.safe_load(open('configuration.yaml'))"
```

<Tip>
  Use 2 spaces for indentation in YAML files. Never use tabs.
</Tip>

### Secrets Not Found

<Warning>
  **Error**: "Secret \[secret\_name] not found"

  **Solution**: Ensure the secret exists in `secrets.yaml` and the name matches exactly (case-sensitive).
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="Developer Docs" icon="code" href="https://developers.home-assistant.io/">
    Explore the full developer documentation
  </Card>

  <Card title="Integration Development" icon="puzzle-piece" href="https://developers.home-assistant.io/docs/creating_component_index">
    Learn to create custom integrations
  </Card>

  <Card title="Configuration Reference" icon="book" href="https://www.home-assistant.io/docs/configuration/">
    Complete configuration reference
  </Card>

  <Card title="Community Forum" icon="comments" href="https://community.home-assistant.io/">
    Get help from the community
  </Card>
</CardGroup>

## Additional Resources

* [Configuration.yaml Examples](https://github.com/home-assistant/core/tree/dev/homeassistant/components)
* [YAML Syntax Guide](https://www.home-assistant.io/docs/configuration/yaml/)
* [Secrets Documentation](https://www.home-assistant.io/docs/configuration/secrets/)
* [Splitting Configuration](https://www.home-assistant.io/docs/configuration/splitting_configuration/)