Summary of changes​

Providing hass argument to the following service helpers is deprecated: verify_domain_control, extract_entity_ids, async_extract_entities, async_extract_entity_ids, and async_extract_config_entry_ids.

Since release 2025.1 (via core PR #133062), a reference to HomeAssistant is available as a property of the ServiceCall object, and it became redundant to pass the hass object to the above helpers.

To update your integration, just remove the hass argument.

Support for the hass argument will be removed in Home Assistant 2026.10.

Examples​

ID extraction helpers​

# Old
# target_entry_ids = await async_extract_config_entry_ids(hass, service_call)
# entity_ids = await async_extract_entity_ids(hass, service_call)
# entities = await service.async_extract_entities(hass, platform_entities.values(), service_call)

# New
target_entry_ids = await async_extract_config_entry_ids(service_call)
entity_ids = await async_extract_entity_ids(service_call)
entities = await service.async_extract_entities(platform_entities.values(), service_call)

Decorator helper​

# Old
# @verify_domain_control(hass, DOMAIN)
# async def do_action(call: ServiceCall) -> None:
#     ...

# New
@verify_domain_control(DOMAIN)
async def do_action(call: ServiceCall) -> None:
    ...

One preferred encoding to represent μ in units of measurement​

The unit prefix μ is used by unit of measurement constants like μV and μS. There are however two different Unicode encodings of μ:

1. The MICRO SIGN
2. The Greek Small Letter Mu

Home Assistant previously mixed the two encodings, which caused issues because string comparisons between the two encodings would fail causing unit of measurement validations to fail.

We chose the "Greek Small Letter Mu" because the "MICRO SIGN" encoding is there for compatibility with old 8-bit western European character sets, and the unicode consortium recommends against using it.

With #144853 we have fixed this in the core of Home Assistant by consequently using the Greek Small Letter Mu version to encode μ. In Python literal strings this variant is encoded as "\u03bc".

Developers should check if their code and libraries have a dependency with the ambiguous MICRO SIGN (μ) "\u00b5", and migrate their code to use the Greek Small Letter Mu "\u03bc" instead to avoid issues.

The sensor and number entity platforms now include a built-in feature to automatically convert units that use the ambiguous MICRO SIGN (μ) encoding.

Find instances in Visual Studio Code​

In Visual Studio Code, enable Match Case in the Search (files) panel to find only the chosen encoding. Copy the exact μ character from above and paste it into the search box. The editor’s page search matches all variants; use the global search instead.

New linter​

To avoid issues with new or changed code, #144853 adds a linter that warns about incorrect literal assignments using the non-preferred encoding of μ.

The DeviceEntry.suggested_area attribute is deprecated and will be removed in HA Core 2026.9. Also, suggested_area will no longer be present in EVENT_DEVICE_REGISTRY_UPDATED events when HA Core 2026.9 is released.

Note: Setting suggested_area in DeviceInfo, and passing suggested_area to DeviceRegistry.async_get_or_create is still supported and influences the area of created devices, although that may change in the future.

Use DeviceEntry.area_id to determine a device’s area in custom integrations. Don’t access DeviceEntry.suggested_area.

During the deprecation period, accessing DeviceEntry.suggested_area will log a warning.

For more details, refer to the DeviceEntry documentation and core PR 149730 which deprecated DeviceEntry.suggested_area.

The result attribute has been removed from the homeassistant.data_entry_flow.FlowResult typed dict, and is now present only when needed, i.e. homeassistant.auth.models.AuthFlowResult and homeassistant.config_entries.ConfigFlowResult.

The change is not expected to affect runtime behavior of custom integrations, but custom integration authors may need to update tests and any classes derived from homeassistant.data_entry_flow.FlowResult that use a result attribute, to silence type-checker warnings.

Helper integrations should not add their own config entries to the source entity's device or to a user selected device. Instead, they should just link their entities to the device of the source entity.

Adding the helper config entry to another integration's device is no longer supported and will stop working in Home Assistant Core 2026.8.

Background​

The architecture proposal home-assistant/architecture#1226 makes device connections and identifiers unique per integration domain instead of globally unique. This is not an issue for most integrations, but helper integrations with config flows are an exception.

Suggested change​

Link the helper entity directly to the source integration's device​

In the helper entity's constructor, set self.device_entry to the source device

class HelperEntity(Entity)

    def __init__(hass: HomeAssistant, source_entity_id: str, ...) -> None:
        self.device_entry = async_entity_id_to_device(
            hass,
            source_entity_id,
        )

Do not add the helper config entry to the source device directly​

Do not add the config entry to the source device directly, meaning that this pattern is no longer allowed

device_registry.async_update_device(
    source_device.id,
    add_config_entry_id=helper_config_entry.entry_id,
)

Do not add the helper config entry to the source device implicitly​

Don’t set self._attr_device_info and don’t override device_info to return identifiers and connections for a device from another integration as that will mean the helper config entry is added to the source device. Instead, Set self.device_entry in the helper entity to link the helper entity to another integration's device as in the example above.

Cleaning up the device registry​

A helper function, homeassistant.helpers.helper_integration.async_remove_helper_config_entry_from_source_device is available to aid the clean up. Core integrations have been modified to call this helper from a config entry migration step.

Handling removed devices​

It is up to the helper integration to decide how to handle a removed device; most core helpers set self.device_entry to None. Note that DeviceRegistry.async_get returns None if passed a device_id which doesn't exist.

Sample implementations​

The derivative core integration, which previously added its config entry to the source entity's device, has been updated to just link the helper entity to the source entity's device in core PR #148674.

The template core integration, which previously added its config entry to a user selected device, has been updated to just link the helper entity to the user selected device in core PR #148756.

The media player state MediaPlayerState.STANDBY has been deprecated as decided in home-assistant/architecture#799 and will be removed in Home Assistant Core 2026.8. Integrations should use MediaPlayerState.IDLE or MediaPlayerState.OFF instead.

For more details, see the media player developer documentation.

With the release of Home Assistant OS 16, the default limit for open file descriptors in Docker containers (and, by extension, all add-ons and the processes within them) has changed. Home Assistant OS now uses the default values provided by Systemd: a soft limit of 1024 and a hard limit of 524288 open files.

This is a change from previous OS versions, where the limit was set to "infinity" (effectively a value over 1 billion) — also introduced as an upstream change — since Home Assistant OS 10. The new limits are consistent with common practices on modern Linux systems and follow changes gradually being adopted across other Linux distributions.

For more details on these limits and best practices, see Lennart Poettering's explanation on File Descriptor Limits. In summary, applications that require more than the default soft limit of 1024 file descriptors should explicitly raise their own limit at startup, up to the hard limit imposed by the system (in our case, 524288). This approach ensures each application only requests the resources it needs and avoids system-wide high limits that may lead to unexpected resource exhaustion.

What does this mean for add-on developers?​

• If your application running as an add-on needs to open more than 1024 files (sockets, pipes, etc.), you should adjust the limit yourself, for example using ulimit -Sn <value>, as long as <value> does not exceed the hard limit (which can be checked with ulimit -Hn).
• Most add-ons will likely not be affected by this change, but some — such as those handling many network connections or accessing numerous files (e.g., databases or file sharing applications) — may need to adapt their startup routines.

What happens if the limit is too low?​

If an add-on or its application requires more file descriptors than the default soft limit (1024) and does not raise the limit itself, it may fail to open additional files, sockets, or network connections once the limit is reached. This typically results in errors such as "Too many open files" or "No file descriptors available" (EMFILE), failing network connections, or malfunctioning services.

If you have any questions or encounter issues, please refer to this GitHub discussion, which also contains more details and background information about this topic.

As of Home Assistant Core 2025.8, the two properties for battery in StateVacuumEntity, battery_level and battery_icon, have been deprecated.

The battery_level and battery_icon properties should be replaced by a separate sensor with the battery sensor device class and optionally a customized icon if the default icon of the battery sensor device class isn't wanted. Optionally consider to also provide a binary sensor with the charging device class if it's currently charging or not.

There is a one-year deprecation period, and the two battery properties will stop working from 2026.8 to ensure all custom integration authors have time to adjust.

More details can be found in the architectural decision.

If a numeric sensor doesn't have a suggested display precision set by its integration, Home Assistant will now use a default display precision based on the sensor's device class.

New device classes should be added to UNITS_PRECISION in homeassistant/components/sensor/const.py, along with the proper unit and the desired default display precision. See the docstring of that constant for more details on how to choose the right unit and precision.

The rounding that was previously applied to the sensor state when a unit conversion was happening is now removed, and the sensor state contains the full raw value.

It is still recommended that integrations set the suggested_display_precision on their sensors. This change is a fallback mechanism to ensure a consistent experience across all numeric sensors.

For more details check the implementation pull request and the Sensor entity documentation.

Icon translations now support defining icons based on numeric ranges. This means integration authors can define icons that change based on numeric values without implementing custom logic in their code.

Previously, icon translations only supported state-based icons, where specific states would map to specific icons. While this works well for discrete states like "on"/"off", it required custom code to handle numeric values like battery levels or signal strength indicators.

Range-based icons are defined in the icons.json file:

{
  "entity": {
    "sensor": {
      "battery_level": {
        "default": "mdi:battery",
        "range": {
          "0": "mdi:battery-outline",
          "10": "mdi:battery-10",
          "20": "mdi:battery-20",
          "30": "mdi:battery-30",
          "40": "mdi:battery-40",
          "50": "mdi:battery-50",
          "60": "mdi:battery-60",
          "70": "mdi:battery-70",
          "80": "mdi:battery-80",
          "90": "mdi:battery-90",
          "100": "mdi:battery"
        }
      }
    }
  }
}

The system selects the icon associated with the highest range value that's less than or equal to the entity's current value. For example:

• A value of 15 will show the mdi:battery-10 icon
• A value of 45 will show the mdi:battery-40 icon
• A value of 100 will show the mdi:battery icon

For implementation details, see the icon translations documentation.