---
id: homeassistant-stubs
version: "2026.8.1"
license: MIT
license_treatment: permissive
maintenance: active
---

# homeassistant-stubs — PEP 484 typing stubs for Home Assistant Core

License: permissive · Maintenance: active · Downloads: 120.9K/mo

## What it is and what it does

This is an unofficial stub-only package that extracts type information from Home Assistant Core sources to enable type checking. It works by running stubgen (from mypy) against strictly typed modules in Home Assistant, then publishing the generated stubs automatically every 12 hours. The package is designed as a development dependency to be added alongside your Home Assistant custom component or AppDaemon app project.

Home Assistant maintainers do not distribute typing information with the main homeassistant package because PEP 561 requires the entire package to support type checking, but many Home Assistant components lack type hints. This stub package solves that by providing type information for core modules and components that are strictly typed, allowing mypy and other type checkers to validate your code against Home Assistant's API.

Use it for:

- Enable mypy type checking in a custom Home Assistant component before deployment
- Validate AppDaemon app code against Home Assistant API types during development
- Catch type errors in Home Assistant integrations during CI/CD before runtime
- Develop Home Assistant automations with IDE autocomplete and type hints

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Provides PEP 484 type stubs for Home Assistant Core, enabling static type checking of Home Assistant custom components and AppDaemon apps against strictly typed core and component modules.

Yes, if you are developing Home Assistant custom components or AppDaemon apps and want static type checking. Install as a dev dependency only. Note that requires_python is >=3.14.2, which is newer than most current Python versions—verify your project's Python version supports this before installing.

## Install

pip install homeassistant-stubs
uv add homeassistant-stubs
poetry add homeassistant-stubs

## Installing homeassistant-stubs

Before you install: Low friction installation as a dev-only dependency. Package is actively maintained with releases every 12 hours, last commit 2026-08-08, and has been stable since first release in 2021-03-31.

License in practice: MIT license (permissive) means you can use this freely in any project, commercial or otherwise, with minimal restrictions.

Quickstart:

# Add to dev dependencies
uv add --dev homeassistant-stubs

# Then use mypy to type-check your custom component
mypy my_custom_component/

Requires Python >=3.14.2, which may be newer than your current environment. Also requires homeassistant as a runtime dependency in your project.

Verify before relying:

- Whether stubs cover all components needed for your specific use case, or only strictly typed core modules and some components as documented

## Package facts

- License: MIT (permissive)
- Python support: capped_below_current
- Install friction: low
- Maintenance: active
- Downloads: 120.9K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

home assistant type stubs, homeassistant typing pep 484, type checking home assistant, mypy stubs homeassistant, home automation type hints, homeassistant static analysis, type-stubs, home-automation

[View on SkillFed](https://skillfed.io/packages/homeassistant-stubs) · [View on PyPI](https://pypi.org/project/homeassistant-stubs/)