homeassistant-stubs

2026.4.4 verified Fri May 01 auth: no python

PEP 484 typing stubs for Home Assistant Core. Provides type annotations for the homeassistant package to enable static type checking with mypy or pyright. Version 2026.4.4 tracks Home Assistant releases; updated frequently alongside HA releases.

pip install homeassistant-stubs

Common errors

error Cannot find reference 'HomeAssistant' in 'homeassistant.core' ↓

cause homeassistant-stubs not installed or version mismatch.

fix

pip install homeassistant-stubs==<your ha version>

error Module 'homeassistant' has no attribute 'config' ↓

cause Stubs missing for certain submodules; HA core may expose it at runtime but stubs lag.

fix

Ignore with # type: ignore[attr-defined] or upgrade stubs.

Warnings

gotcha Stubs must match the exact installed homeassistant version. Mismatch may cause false positives or errors. ↓

fix Pin homeassistant-stubs to the same version as homeassistant, e.g., homeassistant-stubs==2026.4.4.

deprecated Older versions may not include stubs for newer HA modules; always upgrade stubs after upgrading Home Assistant. ↓

fix Update both packages: pip install --upgrade homeassistant homeassistant-stubs

Imports

homeassistant
```
import homeassistant
```
Stubs are installed alongside the package; no special import needed.

Quickstart

Basic usage verifying stubs work with mypy: no additional imports required.

import homeassistant
from homeassistant.core import HomeAssistant

ha = HomeAssistant()
print('Type stubs are active')