G

--- title: 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](config_entries_config_flow_handler.md) as defined by the component. Config entries can also have an extra [options flow handler](config_entries_options_flow_handler.md), also defined by the component. ## Lifecycle | State | Description | | ----- | ----------- | | not loaded | The config entry has not been loaded. This is the initial state when a config entry is created or when Home Assistant is restarted. | | loaded | The config entry has been loaded. | | setup error | An error occurred when trying to set up the config entry. | | setup retry | A 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 error | The config entry had to be migrated to a newer version, but the migration failed. | failed unload | The config entry was attempted to be unloaded, but this was either not supported or it raised an exception. ## Setting up an entry During startup, Home Assistant first calls the [normal component setup](/creating_component_index.md), 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](https://github.com/home-assistant/core/blob/0.68.0/homeassistant/components/hue/__init__.py#L119)). ### 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](https://github.com/home-assistant/core/blob/0.68.0/homeassistant/components/hue/bridge.py#L81)): ```python # Use `hass.async_create_task` to avoid a circular dependency between the platform and the component hass.async_create_task( hass.config_entries.async_forward_entry_setup( config_entry, "light" ) ) ``` For a platform to support config entries, it will need to add a setup entry method ([example](https://github.com/home-assistant/core/blob/0.68.0/homeassistant/components/light/hue.py#L60)): ```python async def async_setup_entry(hass, config_entry, async_add_devices): """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](https://github.com/home-assistant/core/blob/0.68.0/homeassistant/components/hue/__init__.py#L136)). For each platform that you forwarded the config entry to, you will need to forward the unloading too. ```python 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`](core/entity.md#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: ```python async def async_remove_entry(hass, entry) -> None: """Handle removal of an entry.""" ```