Skip to main content

Config entries

Config Entries are configuration data that are persistently stored by Home Assistant. A config entry is created by a user via the UI. The UI flow is powered by a config flow handler as defined by the component. Config entries can also have an extra options flow handler, also defined by the component.

Lifecycle​

StateDescription
not loadedThe config entry has not been loaded. This is the initial state when a config entry is created or when Home Assistant is restarted.
loadedThe config entry has been loaded.
setup errorAn error occurred when trying to set up the config entry.
setup retryA dependency of the config entry was not ready yet. Home Assistant will automatically retry loading this config entry in the future. Time between attempts will automatically increase.
migration errorThe config entry had to be migrated to a newer version, but the migration failed.
failed unloadThe config entry was attempted to be unloaded, but this was either not supported or it raised an exception.

More information about surfacing errors and requesting a retry are in Handling Setup Failures.

Gnot loadednot loadedloadedloadednot loaded->loadedsetup errorsetup errornot loaded->setup errorsetup retrysetup retrynot loaded->setup retrymigration errormigration errornot loaded->migration errorloaded->not loadedfailed unloadfailed unloadloaded->failed unloadsetup error->not loadedsetup retry->not loaded

Setting up an entry​

During startup, Home Assistant first calls the normal component setup, and then call the method async_setup_entry(hass, entry) for each entry. If a new Config Entry is created at runtime, Home Assistant will also call async_setup_entry(hass, entry) (example).

For platforms​

If a component includes platforms, it will need to forward the Config Entry to the platform. This can be done by calling the forward function on the config entry manager (example):

await hass.config_entries.async_forward_entry_setups(config_entry, ["light", "sensor", "switch"])

For a platform to support config entries, it will need to add a setup entry method (example):

async def async_setup_entry(hass, config_entry, async_add_entities):
    """Set up entry."""

Unloading entries​

Components can optionally support unloading a config entry. When unloading an entry, the component needs to clean up all entities, unsubscribe any event listener and close all connections. To implement this, add async_unload_entry(hass, entry) to your component (example).

For each platform that you forwarded the config entry to, you will need to forward the unloading too.

await self.hass.config_entries.async_forward_entry_unload(self.config_entry, "light")

If you need to clean up resources used by an entity in a platform, have the entity implement the async_will_remove_from_hass method.

Removal of entries​

If a component needs to clean up code when an entry is removed, it can define a removal method:

async def async_remove_entry(hass, entry) -> None:
    """Handle removal of an entry."""

Migrating config entries to a new version​

If the config entry version is changed, async_migrate_entry must be implemented to support the migration of old entries. This is documented in detail in the config flow documentation

async def async_migrate_entry(hass: HomeAssistant, config_entry: ConfigEntry) -> bool:
    """Migrate old entry."""

Modifying a config entry​

A ConfigEntry object, including the data and options, must never be mutated directly by integrations, instead integrations must call async_update_entry, the use of which is illustrated in the config flow documentation.