# Home Assistant Core Config Update Mechanism and Event System Explained

> Understand the Home Assistant core config update mechanism and event system. Learn how async_update fires core_config_updated events to notify listeners.

- Repository: [Home Assistant/core](https://github.com/home-assistant/core)
- Tags: internals
- Published: 2026-02-28

---

**Home Assistant propagates core configuration changes via the `Config.async_update()` method in [`homeassistant/core_config.py`](https://github.com/home-assistant/core/blob/main/homeassistant/core_config.py), which fires the internal `core_config_updated` event through the `EventBus` to notify all registered listeners across integrations.**

Home Assistant's architecture relies on a centralized configuration management system to handle critical settings like latitude, longitude, time zone, and unit system. The **core config update mechanism** ensures that when these values change, every component that depends on them receives immediate notification through the internal event system. This implementation resides primarily in the `home-assistant/core` repository, specifically within the [`homeassistant/core_config.py`](https://github.com/home-assistant/core/blob/main/homeassistant/core_config.py) and [`homeassistant/core.py`](https://github.com/home-assistant/core/blob/main/homeassistant/core.py) modules.

## How Home Assistant Stores Core Configuration

The foundation of the **core config update mechanism** is the `Config` class defined in [`homeassistant/core_config.py`](https://github.com/home-assistant/core/blob/main/homeassistant/core_config.py). This class acts as the single source of truth for system-wide settings including language, currency, country, time zone, elevation, and the unit system (metric or imperial).

When Home Assistant starts, it instantiates this `Config` object and loads values from persistent storage. The class provides the `async_update()` method (lines 69-74) as the exclusive entry point for modifying these values at runtime, ensuring that all changes are validated, persisted, and broadcast consistently.

## The Config Update Flow

When an integration or the frontend requests a configuration change, the system executes a precise sequence to ensure data integrity and event propagation.

### Step 1: Persist and Fire the Event

The `Config.async_update()` method handles the entire transaction:

```python

# homeassistant/core_config.py (lines 69-74)

async def async_update(self, **kwargs: Any) -> None:
    """Update the configuration from a dictionary."""
    await self._async_update(source=ConfigSource.STORAGE, **kwargs)
    await self._async_store()
    # Fire internal event to notify all listeners

    self.hass.bus.async_fire_internal(EVENT_CORE_CONFIG_UPDATE, kwargs)

```

The `kwargs` dictionary contains only the changed keys, such as `{"latitude": 51.5, "unit_system": "metric"}`. The call to `self.hass.bus.async_fire_internal()` creates an internal event that bypasses the public `event` service, keeping the notification lightweight and internal-only.

### Step 2: EventBus Dispatch

The `EventBus` class in [`homeassistant/core.py`](https://github.com/home-assistant/core/blob/main/homeassistant/core.py) (line 1422) implements the `async_fire_internal` method:

```python

# homeassistant/core.py

class EventBus:
    def async_fire_internal(self, event_type: str, event_data: Any = None) -> None:
        """Fire an internal event (no public service exposure)."""
        self._async_process_event(
            Event(event_type, data=event_data, event_id=self._next_event_id()),
            internal=True,
        )

```

This method constructs an `Event` object using the constant `EVENT_CORE_CONFIG_UPDATE` (defined in [`homeassistant/const.py`](https://github.com/home-assistant/core/blob/main/homeassistant/const.py), line 263) and delivers it to all registered internal listeners without exposing it to external automation triggers.

## How Components Listen for Config Changes

Integrations that depend on core configuration—such as `sun`, `time_date`, `zone`, and `utility_meter`—register listeners during their setup phase to react to `EVENT_CORE_CONFIG_UPDATE`.

### Registration Pattern

Components typically register in their `async_setup_entry` or initialization code:

```python

# homeassistant/components/sun/entity.py

async def async_setup_entry(hass, entry):
    hass.bus.async_listen(EVENT_CORE_CONFIG_UPDATE, self.update_location)

# homeassistant/components/time_date/sensor.py

self.hass.bus.async_listen(EVENT_CORE_CONFIG_UPDATE, async_update_config)

```

### Callback Execution

When the event fires, the callback receives the event data dictionary containing the changed configuration keys. The component can then recompute values—such as recalculating sunrise times when latitude changes or reformatting time displays when the time zone updates.

## Practical Implementation Examples

### Manually Triggering a Core Config Change

Custom components or automations can programmatically update core settings:

```python

# Update location and unit system

await hass.config.async_update(
    latitude=52.5200,
    longitude=13.4050,
    unit_system="metric",
)

# All listeners to EVENT_CORE_CONFIG_UPDATE receive notification automatically

```

### Building a Custom Listener

To react to configuration changes in a custom integration:

```python
import homeassistant.const as ha_const
from homeassistant.core import HomeAssistant, callback

class MyIntegration:
    def __init__(self, hass: HomeAssistant):
        self.hass = hass
        self.hass.bus.async_listen(
            ha_const.EVENT_CORE_CONFIG_UPDATE, 
            self._handle_core_change
        )

    @callback
    def _handle_core_change(self, event):
        """Re-evaluate configuration-dependent logic."""
        new_tz = event.data.get("time_zone")
        if new_tz:
            self._apply_time_zone(new_tz)

```

## Summary

- **Core configuration** is managed by the `Config` class in [`homeassistant/core_config.py`](https://github.com/home-assistant/core/blob/main/homeassistant/core_config.py), which handles settings like location, time zone, and unit system.
- **Updates propagate via `Config.async_update()`**, which persists changes to storage and immediately fires the `EVENT_CORE_CONFIG_UPDATE` internal event.
- **The `EventBus` in [`homeassistant/core.py`](https://github.com/home-assistant/core/blob/main/homeassistant/core.py) dispatches events** through `async_fire_internal`, ensuring internal-only delivery without public service overhead.
- **Integrations register listeners** using `hass.bus.async_listen(EVENT_CORE_CONFIG_UPDATE, callback)` to recompute state when core settings change, as seen in the `sun`, `time_date`, and `zone` components.

## Frequently Asked Questions

### How do I listen for core configuration changes in a custom component?

Register a listener using `hass.bus.async_listen` with the `EVENT_CORE_CONFIG_UPDATE` constant from `homeassistant.const`. Your callback function will receive an event object containing the changed configuration keys in `event.data`, allowing you to update your component's internal state accordingly.

### What is the difference between `async_fire` and `async_fire_internal` in the Home Assistant EventBus?

`async_fire_internal` creates and dispatches events that bypass the public `event` service and external automation triggers, making it suitable for internal system notifications like configuration updates. The standard `async_fire` method exposes events to the public API, allowing automations and external systems to react to them.

### Which Home Assistant components typically react to `EVENT_CORE_CONFIG_UPDATE`?

Components that depend on location, time, or measurement units register for this event, including the `sun` integration (recalculates sunrise/sunset), `time_date` sensors (reformats display), `zone` (updates geofencing), and `utility_meter` (adjusts unit conversions). Any integration accessing `hass.config` values should consider listening for these updates.

### Can I manually trigger a core configuration update from an automation or script?

Yes, you can call `hass.config.async_update()` from a custom component or Python script, passing the configuration keys you want to change such as `latitude`, `longitude`, `time_zone`, or `unit_system`. This will persist the changes to storage and automatically notify all registered listeners via the internal event system.