Local brand images for custom integrations​

Add a brand/ directory to your custom integration with your icon and logo files:

custom_components/my_integration/
├── __init__.py
├── manifest.json
└── brand/
    ├── icon.png
    └── logo.png

The following image filenames are supported:

• icon.png / dark_icon.png
• logo.png / dark_logo.png
• icon@2x.png / dark_icon@2x.png
• logo@2x.png / dark_logo@2x.png

Local brand images automatically take priority over images from the brands CDN. That's it — no extra configuration needed.

For more details, see the integration file structure documentation.

Brand images now served through a local API​

To make local brand images possible, all brand images are now served through the Home Assistant local API instead of being fetched directly from the CDN by the browser.

A new brands system integration proxies brand images through two endpoints:

• /api/brands/integration/{domain}/{image} — Integration icons and logos
• /api/brands/hardware/{category}/{image} — Hardware images

Images are cached locally on disk and served with a stale-while-revalidate strategy, so they remain available during internet outages.

Impact on the frontend​

The brandsUrl() and hardwareBrandsUrl() helpers in src/util/brands-url.ts now return local API paths instead of CDN URLs. If your custom card or panel uses these helpers, no changes are needed.

If you are constructing brand image URLs manually, update them:

// Old
const url = `https://brands.home-assistant.io/_/${domain}/icon.png`;

// New
import { brandsUrl } from "../util/brands-url";
const url = brandsUrl({ domain, type: "icon" });

These endpoints require authentication. The brandsUrl() helper handles this automatically by appending an access token. If you construct URLs manually, obtain a token via the brands/access_token WebSocket command and append it as a token query parameter.

In October 2022, Home Assistant migrated the preferred color temperature unit from mired to kelvin.

In February 2024, Home Assistant requested explicit supported_color_modes and color_mode properties (triggering deprecation of legacy fallback color mode support).

In December 2024, Home Assistant requested explicit Kelvin support (triggering deprecation of mired support).

It is now time to clean up the legacy code and remove the corresponding attributes, constants and properties:

• Remove deprecated ATTR_COLOR_TEMP, ATTR_MIN_MIREDS, ATTR_MAX_MIREDS, ATTR_KELVIN, COLOR_MODE_***, and SUPPORT_*** constants
• Remove deprecated state attributes ATTR_COLOR_TEMP, ATTR_MIN_MIREDS and ATTR_MAX_MIREDS
• Remove deprecated support for ATTR_KELVIN and ATTR_COLOR_TEMP arguments from the light.turn_on service call
• Remove deprecated support for LightEntity.color_temp, LightEntity.min_mireds and LightEntity.max_mireds properties from the entity
• Remove deprecated support for LightEntity._attr_color_temp, LightEntity._attr_min_mireds and LightEntity._attr_max_mireds shorthand attributes from the entity

Additionally, failing to provide valid supported_color_modes and color_mode properties no longer works and will raise an error.

Examples​

Custom minimum/maximum color temperature​

class MyLight(LightEntity):
    """Representation of a light."""

    # Old
    # _attr_min_mireds = 200 # 5000K
    # _attr_max_mireds = 400 # 2500K

    # New
    _attr_min_color_temp_kelvin = 2500 # 400 mireds
    _attr_max_color_temp_kelvin = 5000 # 200 mireds

Default minimum/maximum color temperature​

from homeassistant.components.light import DEFAULT_MAX_KELVIN, DEFAULT_MIN_KELVIN

class MyLight(LightEntity):
    """Representation of a light."""

    # Old did not need to have _attr_min_mireds / _attr_max_mireds set
    # New needs to set the default explicitly
    _attr_min_color_temp_kelvin = DEFAULT_MIN_KELVIN
    _attr_max_color_temp_kelvin = DEFAULT_MAX_KELVIN

Dynamic minimum/maximum color temperature​

from homeassistant.util import color as color_util

class MyLight(LightEntity):
    """Representation of a light."""

    # Old
    # def min_mireds(self) -> int:
    #     """Return the coldest color_temp that this light supports."""
    #     return device.coldest_temperature
    #
    # def max_mireds(self) -> int:
    #     """Return the warmest color_temp that this light supports."""
    #     return device.warmest_temperature

    # New
    def min_color_temp_kelvin(self) -> int:
        """Return the warmest color_temp that this light supports."""
        return color_util.color_temperature_mired_to_kelvin(device.warmest_temperature)

    def max_color_temp_kelvin(self) -> int:
        """Return the coldest color_temp that this light supports."""
        return color_util.color_temperature_mired_to_kelvin(device.coldest_temperature)

Checking color temperature in service call​

from homeassistant.components.light import ATTR_COLOR_TEMP_KELVIN
from homeassistant.util import color as color_util

class MyLight(LightEntity):
    """Representation of a light."""
    def turn_on(self, **kwargs: Any) -> None:
        """Turn on the light."""
        # Old
        # if ATTR_COLOR_TEMP in kwargs:
        #     color_temp_mired = kwargs[ATTR_COLOR_TEMP]
        #     color_temp_kelvin = color_util.color_temperature_mired_to_kelvin(color_temp_mired)

        # Old
        # if ATTR_KELVIN in kwargs:
        #     color_temp_kelvin = kwargs[ATTR_KELVIN]
        #     color_temp_mired = color_util.color_temperature_kelvin_to_mired(color_temp_kelvin)

        # New
        if ATTR_COLOR_TEMP_KELVIN in kwargs:
            color_temp_kelvin = kwargs[ATTR_COLOR_TEMP_KELVIN]
            color_temp_mired = color_util.color_temperature_kelvin_to_mired(color_temp_kelvin)

Background information​

• Community discussion about Kelvin temperature
• Core PR #79591: Migration to Kelvin
• Architecture discussion #564
• Color modes documentation

Starting as of 2026.3, we're enhancing how the OAuth 2.0 helper handles token request and refresh token failures. This change makes error handling more robust, decoupled from the aiohttp library and helps integrations, that utilize the Data Update Coordinator, to automatically trigger the right error handling.

What changes​

When an OAuth 2.0 token request or token refresh failed, Home Assistant would allow the underlying aiohttp.ClientResponseError to propagate directly to the integration. This behavior is being changed and enhanced.

We're introducing three new exceptions that provide clearer semantics:

• OAuth2TokenRequestTransientError - Recoverable errors, that can be retried.
• OAuth2TokenRequestReauthError - Non-recoverable errors, that require a reauthentication.
• OAuth2TokenRequestError - Base exception for when the above two criteria aren't met or to enable the integration to catch all token request exceptions.

Data Update Coordinator​

Most integrations that use the OAuth 2.0 helper, also use the Data Update Coordinator. When a token request or refresh token fails, the exceptions will bubble up in the Data Update Coordinator and now triggers the following error handling:

For unrecoverable errors (400+, except 429 (rate limit)):

• OAuth2TokenRequestReauthError: Data Update Coordinator raises ConfigEntryAuthFailed if exceptions should be raised or starts a reauthentication flow.

For transient errors (500+ and 429):

• OAuth2TokenRequestTransientError: Data Update Coordinator treats it as an UpdateFailed and the retry mechanism will be triggered.

This means that integrations that use the OAuth 2.0 helper in combination with the Data Update Coordinator don’t need to do any special handling of the new exceptions.

Migration​

Integrations that today use the OAuth 2.0 helper and handle aiohttp.ClientResponseError explicitly should adjust their error handling to deal with the new exceptions. To ease this transition, we have added a compatibility layer by having the new OAuth exceptions inherit from aiohttp.ClientResponseError. Existing code that catches this exception type should continue to work. It is however encouraged to refactor the code to use the new exceptions. See the code example for details.

Code example of migration​

Update the exception handling and then continue to work out if it's a (non-)recoverable error in the integration. For example:

    try:
        await auth.async_get_access_token()
    except OAuth2TokenRequestReauthError as err:
        raise ConfigEntryAuthFailed(
            translation_domain=DOMAIN, translation_key="reauth_required"
        ) from err
    except (OAuth2TokenRequestError, ClientError) as err:
        raise ConfigEntryNotReady(
            translation_domain=DOMAIN, translation_key="auth_server_error"
        ) from err

Custom integrations using the webhook config flow helper must add translation strings for the reconfiguration flow.

Example translation strings for a reconfiguration flow:

{
  "config": {
    "abort": {
      "reconfigure_successful": "**Reconfiguration was successful**\n\nIn Sleep as Android go to *Settings → Services → Automation → Webhooks* and update the webhook with the following URL:\n\n`{webhook_url}`"
    },
    "step": {
      "reconfigure": {
        "description": "Are you sure you want to re-configure the Sleep as Android integration?",
        "title": "Reconfigure Sleep as Android"
      }
    }
  }
}

For more details, see core PR #151729.

The new async_subscribe_preview_feature function provides a more consistent API, where the listener callback receives an EventLabsUpdatedData parameter containing the updated feature state. This eliminates the need to separately call async_is_preview_feature_enabled inside the listener to check the current value.

Old usage​

from homeassistant.components.labs import async_is_preview_feature_enabled, async_listen

def my_listener() -> None:
    if async_is_preview_feature_enabled(hass, DOMAIN, "my_feature"):
        # feature enabled
        ...

async_listen(
    hass,
    domain=DOMAIN,
    preview_feature="my_feature",
    listener=my_listener,
)

New usage​

from homeassistant.components.labs import EventLabsUpdatedData, async_subscribe_preview_feature

async def my_listener(event_data: EventLabsUpdatedData) -> None:
    if event_data["enabled"]:
        # feature enabled
        ...

async_subscribe_preview_feature(
    hass,
    domain=DOMAIN,
    preview_feature="my_feature",
    listener=my_listener,
)

Note that the new listener is a coroutine function and receives EventLabsUpdatedData as a parameter.

async_listen will be removed in Home Assistant 2027.3.

For more details, see core PR #162648.

New development environments will automatically install prek and for existing ones please just update the test requirements by running uv pip install requirements_test.txt

Starting in 2026.7, installation of pyserial-asyncio will be blocked in Home Assistant.

Library maintainers and custom integrations are advised to migrate to pyserial-asyncio-fast.

Background​

pyserial-asyncio blocks the event loop because it does a blocking sleep. The library is also not maintained so efforts to improve the situation haven't been released.

pyserial-asyncio-fast was created as a drop-in replacement (see the repository), and all core integrations have now been migrated.

Migration​

pyserial-asyncio-fast was designed as a drop-in replacement of pyserial-asyncio, and the necessary changes are trivial.

Requirements​

# Old
  install_requires=[
    "pyserial-asyncio"
  ]

# New
  install_requires=[
    "pyserial-asyncio-fast"
  ]

Usage​

# Old
import serial_asyncio

async def connect():
    conn = await serial_asyncio.open_serial_connection(**self.serial_settings)

# New
import serial_asyncio_fast

async def connect():
    conn = await serial_asyncio_fast.open_serial_connection(**self.serial_settings)

More examples are available in the tracking pull request.

The service action example now shows how to supply the available description placeholders during the registration of the service action.

Move URLs from service descriptions and translation strings into description placeholders.

If serialize_in_event_loop is True (the default):

• The data_func passed to Store.async_delay_save is called from the event loop
• Data produced by data_func passed to Store.async_delay_save is serialized to JSON in the event loop
• Data passed to Store.async_save is serialized to JSON in the event loop

If serialize_in_event_loop is False:

• The data_func passed to Store.async_delay_save is called from a separate thread, which means it must be thread safe and must not access the hass object
• Data produced by data_func passed to Store.async_delay_save is serialized to JSON in a separate thread, which means it must be thread safe
• Data passed to Store.async_save is serialized to JSON in a separate thread, which means it must be thread safe

The behavior has changed; data_func passed to Store.async_delay_save was previously always called from a separate thread and data produced by it or data passed to Store.async_save was previously always serialized by a separate thread.

The reason for the change is that it was not documented that data_func would be called by a thread other than the event loop or that JSON serialization would happen in a thread other than the event loop, and the data_func and data produced by it or passed to Store.async_save was generally not thread safe.

For more details, see core PR 157158 and core PR 157263.

Integrations that use MQTT might need to wait for a subscription to complete before they initiate actions. The default behavior is that a subscription is queued and debounced, so callers usually do not wait for broker confirmation. Some integrations must guarantee that the broker finished the subscription.

The new mqtt.async_on_subscribe_done helper can be used to monitor MQTT subscriptions, to allow doing additional tasks. Make sure the same QoS is used as in the MQTT subscription.

Example:

from homeassistant.components import mqtt

async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
    """Setup integration MQTT subscription monitoring."""

    def _on_subscribe_status() -> None:
        """Handle subscription ready signal."""
        # Do stuff

    # Handle subscription ready status update
    await mqtt.async_on_subscribe_done(
        hass,
        "myintegration/status",
        qos=1,
        on_subscribe_status=_on_subscribe_status,
    )

    # Do stuff

For more details on entity category, see the documentation.

What are Labs preview features?​

Labs preview features are different from beta testing. While beta testing evaluates the stability of upcoming Home Assistant releases, Labs is about refining user interfaces and design. Labs features are fully tested and functional, but their design and behavior may still change as we gather real-world usage and feedback. This means they might have breaking changes, be extended with new functionality, or even be removed if they don't work out.

Think of it this way:

• Beta: Evaluates the stability of upcoming Home Assistant releases
• Labs: Fully tested features with evolving design and user interface, refined through real-world usage and feedback

How it works​

Integrations declare preview features in their manifest.json with links for feedback, documentation, and issue reporting. Users can then enable these features in Settings → System → Labs, and they activate immediately without requiring a restart. The integration code checks whether a feature is enabled and responds accordingly.

Why Labs?​

Many of our most significant improvements benefit from real-world testing before becoming standard. Labs provides:

1. Structured feedback channels: Each feature has dedicated URLs for feedback, documentation, and issue reporting
2. Runtime activation: Features enable and disable instantly, no configuration updates or restart required
3. Clear expectations: Users know they're trying fully tested features whose design may change based on feedback
4. Iterative development: Integrate user feedback directly into the development process

Example: Kitchen Sink special repair​

The Kitchen Sink demo integration includes a working example. When enabled, the "special repair" feature creates a repair issue to demonstrate how Labs features can interact with other Home Assistant integrations. See the developer documentation for the complete implementation.

Getting started​

Ready to add a Labs preview feature to your integration? Check out our comprehensive guide which covers:

• When to use Labs (and when not to)
• How to define features in your manifest
• Implementation patterns for backend and frontend features
• Runtime activation requirements
• Testing approaches
• Feature lifecycle (preview → standard or removal)

What's next?​

We encourage integration developers to consider Labs for:

• Major UI changes or redesigns
• Significant architectural changes that benefit from real-world testing
• Features where user feedback will shape the final design

Labs is not for:

• Permanent configuration options (use integration options instead)
• Minor changes that can go directly into releases
• Features with critical bugs or that are fundamentally incomplete

Try it yourself​

Want to see Labs in action? Install the Kitchen Sink demo integration and enable the "Special repair" feature in Settings → System → Labs. You'll see firsthand how preview features work.

In situations where polling API's would return a sign of being overwhelmed, by throwing an HTTP 429 or providing a Retry-After in the response header, integrations can now honor these backoff signals. The integration and API client must detect these backoff signals and sanitize the API's desired backoff period. The UpdateFailed exception accepts a retry_after parameter (a float in seconds) to delay the next scheduled refresh. Once the API recovers and UpdateFailed is no longer raised, the integration resumes its normal update_interval.

Example of the usage:

try:
    request = await self.client.get_information()
except APIClientRateLimited as err:
    raise UpdateFailed(
        retry_after=60  # This can also be retrieved from the API response itself, or provide a default
    ) from err

ConfigEntryNotReady​

The retry_after parameter is ignored during the Update Coordinator setup phase (async_config_entry_first_refresh). If the first refresh fails, Home Assistant raises a ConfigEntryNotReady exception, allowing config entry setup to retry automatically using the built-in retry. Once the coordinator setup succeeds, retry_after applies to following refreshes.

CalculatedState is the container with state and attributes returned by Entity._async_calculate_state.

For details, see core PR 151672.

Currently integrations using configuration via OAuth2 call config_entry_oauth2_flow.async_get_config_entry_implementation in async_setup_entry in their __init__.py. Previously when there was no network, this would raise ValueError: Implementation not available, which was a non-retryable error, resulting in the integration needing to be manually reconfigured after internet was restored (see Issues 153956 and 144582). core PR 154579 added config_entry_oauth2_flow.ImplementationUnavailableError and raises it in config_entry_oauth2_flow.async_get_config_entry_implementation when OAuth2 configuration is unavailable because of missing internet. Integrations should catch this error and raise ConfigEntryNotReady. The changed behavior with the new exception will be released in 2025.12.

Here is an example of the migration,

-    implementation = await async_get_config_entry_implementation(hass, entry)
+    try:
+        implementation = await async_get_config_entry_implementation(hass, entry)
+    except ImplementationUnavailableError as err:
+        raise ConfigEntryNotReady(
+            "OAuth2 implementation temporarily unavailable, will retry"
+        ) from err

New integrations will find the correct try / except block generated by python3 -m script.scaffold config_flow_oauth2.

For details, see core PR 155689 and core PR 147358.

Legacy, untranslated action names and descriptions from services.yaml remain in both the WebSocket and REST responses.

Fetch complete action translations with the WebSocket command frontend/get_translations.

For details, see core PR 147120.

The following changes have been made to the WS API:

• The WS command recorder/update_statistics_metadata accepts a unit_class that points to the unit converter used for unit conversions. If there is no compatible unit converter, unit_class should be set to null. Not specifying the unit_class is deprecated and will stop working in Home Assistant Core 2026.11.
• The metadata object included in the WS command recorder/import_statistics accepts a unit_class that points to the unit converter used for unit conversions. If there is no compatible unit converter, unit_class should be set to null. Not specifying the unit_class is deprecated and will stop working in Home Assistant Core 2026.11.
• The metadata object included in the WS command recorder/import_statistics accepts a mean_type that specifies the type of mean (0 for no mean, 1 for arithmetic mean, or 2 for circular mean). The mean_type replaces the bool flag has_mean. Not specifying the mean_type is deprecated and will stop working in Home Assistant Core 2026.11.
• The items in the response to the WS commands recorder/list_statistic_ids and recorder/get_statistics_metadata have mean_type and unit_class.
• The has_mean in the items in the response to the WS commands recorder/list_statistic_ids and recorder/get_statistics_metadata is deprecated and will be removed in Home Assistant Core 2026.11.

The following changes have been made to the Python API:

• The function async_update_statistics_metadata accepts a new_unit_class that points to the unit converter used for unit conversions. If there is no compatible unit converter, new_unit_class should be set to None. Not specifying the new_unit_class is deprecated and will stop working in Home Assistant Core 2025.11.
• The metadata object passed to the functions async_import_statistics and async_add_external_statistics accepts a unit_class that points to the unit converter used for unit conversions. If there is no compatible unit converter, unit_class should be set to None. Not specifying the unit_class is deprecated and will stop working in Home Assistant Core 2025.11.
• The metadata object passed to the functions async_import_statistics and async_add_external_statistics accepts a mean_type of type StatisticMeanType that specifies the type of mean (NONE, ARITHMETIC, or CIRCULAR). The mean_type replaces the bool flag has_mean. Not specifying the mean_type is deprecated and will stop working in Home Assistant Core 2026.11.
• The items in the return value of the function async_list_statistic_ids have mean_type and unit_class.
• The has_mean in the items in the return value of the function async_list_statistic_ids is deprecated and will be removed in Home Assistant Core 2026.11.

Hassfest has been updated to fail on services with device filter on targets.

Validation of target selectors that specify a device filter will fail in Home Assistant Core 2026.11.

Background​

Core helpers that extract entities from targets did not support the device filter. When the user picked a floor, area, label, or category, the filter was ignored. The frontend also ignored the device filter when selecting entities for a target.

A review of all core integrations found no correct use of a device filter on target selectors. We removed the device filter from the target selector rather than implement support for it in Core and the frontend.

Impact on custom integrations and blueprints​

Update custom integrations and blueprints to remove device filters from target selectors.

If you have a valid use case for device filters on target selectors, reach out on Discord.

Consider the following case:

async def _update():
    a = await get_a()
    # A: User or other logic request a new update here through async_schedule_update()
    b = await get_b()
    return (a,b)

A user or code that request an updates at timestamp A expects that the entities linked will all get new data from that time. However, since we previously ignored that request, entities would have data for the value of a that is from a time before the update request that was ignored.

To make sure we avoid this case, the update coordinator will now schedule an additional update, if a request is received while currently executing an update.

A side effect of this is that it is now possible to schedule an update from inside an update function of the coordinator. That is useful if for example a connection is lost mid update, and we want all entities to indicate directly as unavailable, yet we want to attempt a re-connect as quick as possible but do that in the next update cycle.