Skip to main content
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

Build docs developers (and LLMs) love

Get started for freeTalk to us