> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/home-assistant/core/llms.txt
> Use this file to discover all available pages before exploring further.

# 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).

<ParamField path="entity_id_or_uuid" type="str" required>
  Entity ID or entity registry entry ID
</ParamField>

<ResponseField name="return" type="RegistryEntry | None">
  Entity entry or None if not found
</ResponseField>

```python theme={null}
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.

<ParamField path="domain" type="str" required>
  Entity domain (e.g., "light", "switch")
</ParamField>

<ParamField path="platform" type="str" required>
  Platform name (e.g., "hue", "mqtt")
</ParamField>

<ParamField path="unique_id" type="str" required>
  Unique identifier from platform
</ParamField>

<ResponseField name="return" type="str | None">
  Entity ID or None if not found
</ResponseField>

```python theme={null}
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.

<ParamField path="domain" type="str" required>
  Entity domain
</ParamField>

<ParamField path="platform" type="str" required>
  Platform name
</ParamField>

<ParamField path="unique_id" type="str" required>
  Unique identifier
</ParamField>

<ParamField path="suggested_object_id" type="str | None | UndefinedType" default="UNDEFINED">
  Suggested object ID for entity\_id generation
</ParamField>

<ParamField path="object_id_base" type="str | None | UndefinedType" default="UNDEFINED">
  Base for object ID (used with has\_entity\_name)
</ParamField>

<ParamField path="config_entry" type="ConfigEntry | None | UndefinedType" default="UNDEFINED">
  Config entry this entity belongs to
</ParamField>

<ParamField path="config_subentry_id" type="str | None | UndefinedType" default="UNDEFINED">
  Config subentry ID
</ParamField>

<ParamField path="device_id" type="str | None | UndefinedType" default="UNDEFINED">
  Device ID this entity belongs to
</ParamField>

<ParamField path="disabled_by" type="RegistryEntryDisabler | None" default="None">
  What disabled the entity (if creating)
</ParamField>

<ParamField path="hidden_by" type="RegistryEntryHider | None" default="None">
  What hid the entity (if creating)
</ParamField>

<ParamField path="has_entity_name" type="bool | UndefinedType" default="UNDEFINED">
  Whether entity name describes only the entity itself
</ParamField>

<ParamField path="entity_category" type="EntityCategory | UndefinedType | None" default="UNDEFINED">
  Category of entity (CONFIG, DIAGNOSTIC)
</ParamField>

<ParamField path="original_name" type="str | None | UndefinedType" default="UNDEFINED">
  Original name as set by integration
</ParamField>

<ParamField path="original_icon" type="str | None | UndefinedType" default="UNDEFINED">
  Original icon as set by integration
</ParamField>

<ParamField path="original_device_class" type="str | None | UndefinedType" default="UNDEFINED">
  Original device class as set by integration
</ParamField>

<ParamField path="supported_features" type="int | None | UndefinedType" default="UNDEFINED">
  Supported features bitfield
</ParamField>

<ParamField path="capabilities" type="Mapping[str, Any] | None | UndefinedType" default="UNDEFINED">
  Entity capabilities
</ParamField>

<ParamField path="unit_of_measurement" type="str | None | UndefinedType" default="UNDEFINED">
  Unit of measurement
</ParamField>

<ParamField path="translation_key" type="str | None | UndefinedType" default="UNDEFINED">
  Translation key for entity name
</ParamField>

<ResponseField name="return" type="RegistryEntry">
  Entity entry (created or existing)
</ResponseField>

```python theme={null}
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.

<ParamField path="entity_id" type="str" required>
  Entity ID to remove
</ParamField>

```python theme={null}
ent_reg.async_remove("light.old_light")
```

#### async\_update\_entity

Update entity attributes.

<ParamField path="entity_id" type="str" required>
  Entity ID to update
</ParamField>

<ParamField path="name" type="str | None | UndefinedType" default="UNDEFINED">
  New name (user-customized)
</ParamField>

<ParamField path="icon" type="str | None | UndefinedType" default="UNDEFINED">
  New icon
</ParamField>

<ParamField path="area_id" type="str | None | UndefinedType" default="UNDEFINED">
  New area ID
</ParamField>

<ParamField path="disabled_by" type="RegistryEntryDisabler | None | UndefinedType" default="UNDEFINED">
  What disabled the entity
</ParamField>

<ParamField path="hidden_by" type="RegistryEntryHider | None | UndefinedType" default="UNDEFINED">
  What hid the entity
</ParamField>

<ParamField path="labels" type="set[str] | UndefinedType" default="UNDEFINED">
  Entity labels
</ParamField>

<ResponseField name="return" type="RegistryEntry">
  Updated entity entry
</ResponseField>

#### async\_get\_available\_entity\_id

Get next available entity ID.

<ParamField path="domain" type="str" required>
  Entity domain
</ParamField>

<ParamField path="suggested_object_id" type="str" required>
  Suggested object ID
</ParamField>

<ParamField path="current_entity_id" type="str | None" default="None">
  Current entity ID (if renaming)
</ParamField>

<ParamField path="reserved_entity_ids" type="set[str] | None" default="None">
  Additional IDs to avoid
</ParamField>

<ResponseField name="return" type="str">
  Available entity ID
</ResponseField>

```python theme={null}
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

<ParamField path="entity_id" type="str">
  Entity ID (format: domain.object\_id)
</ParamField>

<ParamField path="unique_id" type="str">
  Unique identifier from platform
</ParamField>

<ParamField path="platform" type="str">
  Platform name
</ParamField>

<ParamField path="domain" type="str">
  Entity domain
</ParamField>

<ParamField path="id" type="str">
  Unique entry ID (UUID)
</ParamField>

<ParamField path="config_entry_id" type="str | None">
  Config entry ID
</ParamField>

<ParamField path="config_subentry_id" type="str | None">
  Config subentry ID
</ParamField>

<ParamField path="device_id" type="str | None">
  Device ID
</ParamField>

<ParamField path="area_id" type="str | None">
  Area ID
</ParamField>

<ParamField path="labels" type="set[str]">
  Entity labels
</ParamField>

<ParamField path="name" type="str | None">
  User-customized name
</ParamField>

<ParamField path="original_name" type="str | None">
  Original name from integration
</ParamField>

<ParamField path="icon" type="str | None">
  User-customized icon
</ParamField>

<ParamField path="original_icon" type="str | None">
  Original icon from integration
</ParamField>

<ParamField path="device_class" type="str | None">
  User-customized device class
</ParamField>

<ParamField path="original_device_class" type="str | None">
  Original device class from integration
</ParamField>

<ParamField path="disabled_by" type="RegistryEntryDisabler | None">
  What disabled the entity (USER, DEVICE, INTEGRATION, CONFIG\_ENTRY, HASS)
</ParamField>

<ParamField path="hidden_by" type="RegistryEntryHider | None">
  What hid the entity (USER, INTEGRATION)
</ParamField>

<ParamField path="entity_category" type="EntityCategory | None">
  Category of entity (CONFIG, DIAGNOSTIC)
</ParamField>

<ParamField path="has_entity_name" type="bool">
  Whether name describes only the entity itself
</ParamField>

<ParamField path="translation_key" type="str | None">
  Translation key for entity name
</ParamField>

<ParamField path="supported_features" type="int">
  Supported features bitfield
</ParamField>

<ParamField path="capabilities" type="Mapping[str, Any] | None">
  Entity capabilities
</ParamField>

<ParamField path="unit_of_measurement" type="str | None">
  Unit of measurement
</ParamField>

<ParamField path="options" type="ReadOnlyEntityOptionsType">
  Entity-specific options
</ParamField>

<ParamField path="aliases" type="set[str]">
  Alternative names for the entity
</ParamField>

<ParamField path="categories" type="dict[str, str]">
  Categories per scope
</ParamField>

<ParamField path="created_at" type="datetime">
  When entity was created
</ParamField>

<ParamField path="modified_at" type="datetime">
  When entity was last modified
</ParamField>

### Methods

<ResponseField name="disabled" type="bool">
  Whether the entity is disabled
</ResponseField>

<ResponseField name="hidden" type="bool">
  Whether the entity is hidden
</ResponseField>

## Events

### EVENT\_ENTITY\_REGISTRY\_UPDATED

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

```python theme={null}
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.

<ParamField path="hass" type="HomeAssistant" required>
  Home Assistant instance
</ParamField>

<ParamField path="entry" type="RegistryEntry" required>
  Entity entry
</ParamField>

<ParamField path="original_name" type="str | None | UndefinedType" default="UNDEFINED">
  Override for original\_name
</ParamField>

<ResponseField name="return" type="str">
  Full entity name
</ResponseField>

```python theme={null}
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