Entity Registry

Registry for managing and tracking entity IDs in Home Assistant.

The homeassistant.helpers.entity_registry module provides a registry to track entities and their metadata, uniquely identified by their domain, platform, and unique ID.

EntityRegistry Class

The main class for managing entity registration and lookup.

Key Methods

async_get

Get entity entry by entity_id or entity entry id (UUID).

entity_id_or_uuid · str · required

Entity ID or entity registry entry ID

return · RegistryEntry | None

Entity entry or None if not found

from homeassistant.helpers import entity_registry as er

ent_reg = er.async_get(hass)
entry = ent_reg.async_get("light.living_room")

async_get_entity_id

Get entity_id from domain, platform, and unique_id.

domain · str · required

Entity domain (e.g., “light”, “switch”)

platform · str · required

Platform name (e.g., “hue”, “mqtt”)

unique_id · str · required

Unique identifier from platform

return · str | None

Entity ID or None if not found

entity_id = ent_reg.async_get_entity_id(
    "light",
    "hue",
    "00:11:22:33:44:55-1"
)

async_get_or_create

Get entity or create if it doesn’t exist.

domain · str · required

Entity domain

platform · str · required

Platform name

unique_id · str · required

Unique identifier

suggested_object_id · str | None | UndefinedType · default: "UNDEFINED"

Suggested object ID for entity_id generation

object_id_base · str | None | UndefinedType · default: "UNDEFINED"

Base for object ID (used with has_entity_name)

config_entry · ConfigEntry | None | UndefinedType · default: "UNDEFINED"

Config entry this entity belongs to

config_subentry_id · str | None | UndefinedType · default: "UNDEFINED"

Config subentry ID

device_id · str | None | UndefinedType · default: "UNDEFINED"

Device ID this entity belongs to

disabled_by · RegistryEntryDisabler | None · default: "None"

What disabled the entity (if creating)

hidden_by · RegistryEntryHider | None · default: "None"

What hid the entity (if creating)

has_entity_name · bool | UndefinedType · default: "UNDEFINED"

Whether entity name describes only the entity itself

entity_category · EntityCategory | UndefinedType | None · default: "UNDEFINED"

Category of entity (CONFIG, DIAGNOSTIC)

original_name · str | None | UndefinedType · default: "UNDEFINED"

Original name as set by integration

original_icon · str | None | UndefinedType · default: "UNDEFINED"

Original icon as set by integration

original_device_class · str | None | UndefinedType · default: "UNDEFINED"

Original device class as set by integration

supported_features · int | None | UndefinedType · default: "UNDEFINED"

Supported features bitfield

capabilities · Mapping[str, Any] | None | UndefinedType · default: "UNDEFINED"

Entity capabilities

unit_of_measurement · str | None | UndefinedType · default: "UNDEFINED"

Unit of measurement

translation_key · str | None | UndefinedType · default: "UNDEFINED"

Translation key for entity name

return · RegistryEntry

Entity entry (created or existing)

entry = ent_reg.async_get_or_create(
    "light",
    "hue",
    "00:11:22:33:44:55-1",
    config_entry=config_entry,
    device_id=device.id,
    has_entity_name=True,
    original_name="Bulb 1",
    supported_features=5
)

async_remove

Remove an entity from registry.

entity_id · str · required

Entity ID to remove

ent_reg.async_remove("light.old_light")

async_update_entity

Update entity attributes.

entity_id · str · required

Entity ID to update

name · str | None | UndefinedType · default: "UNDEFINED"

New name (user-customized)

icon · str | None | UndefinedType · default: "UNDEFINED"

New icon

area_id · str | None | UndefinedType · default: "UNDEFINED"

New area ID

disabled_by · RegistryEntryDisabler | None | UndefinedType · default: "UNDEFINED"

What disabled the entity

hidden_by · RegistryEntryHider | None | UndefinedType · default: "UNDEFINED"

What hid the entity

labels · set[str] | UndefinedType · default: "UNDEFINED"

Entity labels

return · RegistryEntry

Updated entity entry

async_get_available_entity_id

Get next available entity ID.

domain · str · required

Entity domain

suggested_object_id · str · required

Suggested object ID

current_entity_id · str | None · default: "None"

Current entity ID (if renaming)

reserved_entity_ids · set[str] | None · default: "None"

Additional IDs to avoid

return · str

Available entity ID

entity_id = ent_reg.async_get_available_entity_id(
    "light",
    "living_room"
)
# Returns: "light.living_room" or "light.living_room_2" if taken

RegistryEntry

Frozen dataclass representing an entity registry entry.

Properties

entity_id · str

Entity ID (format: domain.object_id)

unique_id · str

Unique identifier from platform

platform · str

Platform name

domain · str

Entity domain

id · str

Unique entry ID (UUID)

config_entry_id · str | None

Config entry ID

config_subentry_id · str | None

Config subentry ID

device_id · str | None

Device ID

area_id · str | None

Area ID

labels · set[str]

Entity labels

name · str | None

User-customized name

original_name · str | None

Original name from integration

icon · str | None

User-customized icon

original_icon · str | None

Original icon from integration

device_class · str | None

User-customized device class

original_device_class · str | None

Original device class from integration

disabled_by · RegistryEntryDisabler | None

What disabled the entity (USER, DEVICE, INTEGRATION, CONFIG_ENTRY, HASS)

hidden_by · RegistryEntryHider | None

What hid the entity (USER, INTEGRATION)

entity_category · EntityCategory | None

Category of entity (CONFIG, DIAGNOSTIC)

has_entity_name · bool

Whether name describes only the entity itself

translation_key · str | None

Translation key for entity name

supported_features · int

Supported features bitfield

capabilities · Mapping[str, Any] | None

Entity capabilities

unit_of_measurement · str | None

Unit of measurement

options · ReadOnlyEntityOptionsType

Entity-specific options

aliases · set[str]

Alternative names for the entity

categories · dict[str, str]

Categories per scope

created_at · datetime

When entity was created

modified_at · datetime

When entity was last modified

Methods

disabled · bool

Whether the entity is disabled

hidden · bool

Whether the entity is hidden

Events

EVENT_ENTITY_REGISTRY_UPDATED

Fired when an entity is created, updated, or removed.

from homeassistant.helpers.entity_registry import EVENT_ENTITY_REGISTRY_UPDATED

@callback
def entity_updated(event):
    action = event.data["action"]  # "create", "update", or "remove"
    entity_id = event.data["entity_id"]
    if action == "update":
        changes = event.data["changes"]
        old_entity_id = event.data.get("old_entity_id")
    
hass.bus.async_listen(EVENT_ENTITY_REGISTRY_UPDATED, entity_updated)

Helper Functions

async_get_full_entity_name

Get full entity name including device name if appropriate.

hass · HomeAssistant · required

Home Assistant instance

entry · RegistryEntry · required

Entity entry

original_name · str | None | UndefinedType · default: "UNDEFINED"

Override for original_name

return · str

Full entity name

from homeassistant.helpers.entity_registry import async_get_full_entity_name

full_name = async_get_full_entity_name(hass, entry)
# Returns: "Device Name Entity Name" or just "Entity Name"

Enums

RegistryEntryDisabler

What disabled a registry entry.

• CONFIG_ENTRY - Disabled by config entry
• DEVICE - Disabled because device is disabled
• HASS - Disabled by Home Assistant
• INTEGRATION - Disabled by integration
• USER - Disabled by user

RegistryEntryHider

What hid a registry entry.

• INTEGRATION - Hidden by integration
• USER - Hidden by user