Home Assistant Intents

2026.3.24 verified Mon Apr 27 auth: no python

Home Assistant Intents is a community-maintained repository and Python package that provides structured intents (language-specific phrases mapped to actions) for the Home Assistant voice assistant. The package is versioned with a calendar-based scheme (2026.3.24) and releases are tied to the intents repository updates, typically weekly or on-demand. It requires Python >=3.9.

pip install home-assistant-intents

Common errors

error ModuleNotFoundError: No module named 'home-assistant-intents' ↓

cause Trying to import with hyphens in the module name, but Python requires underscores.

fix

Use import home_assistant_intents (underscores) after pip installing home-assistant-intents (hyphens).

error KeyError: 'en' when calling load_intents('en') ↓

cause The load_intents function expects the locale code with region if available, e.g., 'en-US' or 'en-GB'. Bare 'en' may not be present if only regional variants are installed.

fix

Use a full locale code like 'en-US' or 'en-GB', or check available locales via home_assistant_intents.get_locales().

Warnings

gotcha The package is installed as 'home-assistant-intents' (with hyphens) but imported as 'home_assistant_intents' (with underscores). Using 'import home-assistant-intents' will fail with a SyntaxError. ↓

fix Import using underscores: from home_assistant_intents import ...

breaking The load_intents function returns a dictionary keyed by domain (e.g., 'light', 'lock') rather than the flat list of sentences seen in earlier versions. Code relying on a different shape may break. ↓

fix Access intents via the domain key: intents['light'] instead of iterating over intents directly.

deprecated The function 'get_sentence_details' is deprecated as of version 2026.2.0. Use 'intent_for_sentence' instead. ↓

fix Replace get_sentence_details(sentence, intents) with intent_for_sentence(sentence, intents).

Imports

load_intents
wrong
```
import intents
```
correct
```
from home_assistant_intents import load_intents
```
The package is installed as home-assistant-intents but the import uses underscores. Importing 'intents' alone (which is a different library) will break.

get_sentence_details

from home_assistant_intents import get_sentence_details

Quickstart

Load intents for English and retrieve details for a sentence. The intents structure is a dict mapping sentences to action data.

from home_assistant_intents import load_intents, get_sentence_details

# Load intents for a language (e.g., English)
intents = load_intents('en')
# Get details of a specific sentence
sentence = 'turn on the kitchen light'
details = get_sentence_details(sentence, intents)
print(details)