Install & Compatibility
Where this runs
tested against v2023.7.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.13
✕ build_error
✕ build_error
py 3.9
✕ build_error
✓ 23.8s
336MB installed
● package 336MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
HomeAssistant
✓ from homeassistant.core import HomeAssistant
The central coordinator object for Home Assistant operations.
ConfigEntry
✓ from homeassistant.config_entries import ConfigEntry
Used for managing UI-based integration configurations.
DOMAIN
✓ from homeassistant.const import DOMAIN
Common constant used to define an integration's unique identifier.
Platform
✓ from homeassistant.const import Platform
Used for defining entity platforms (e.g., light, sensor).
async_setup_entry
✓ from homeassistant.config_entries import ConfigEntry
async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
The primary asynchronous entry point for setting up UI-configured integrations.
This quickstart demonstrates how to programmatically start and interact with a basic Home Assistant Core instance, primarily for testing or embedding purposes. For integration development, you would typically use the `python3 -m script.scaffold integration` command within a development environment to generate a boilerplate custom component structure, then implement your logic in `__init__.py`, `config_flow.py`, and entity platform files.
import asyncio
from homeassistant.core import HomeAssistant, CoreState
async def run_hass_instance():
hass = HomeAssistant(".homeassistant") # Use a temporary config directory
await hass.async_start()
print(f"Home Assistant started. State: {hass.state}")
# Example: Set a state (e.g., for a custom sensor)
hass.states.async_set("test.hello_world", "Hello from Python!")
print(f"State of test.hello_world: {hass.states.get('test.hello_world').state}")
# Keep running for a short period or until manually stopped
await asyncio.sleep(5)
await hass.async_stop()
print("Home Assistant stopped.")
if __name__ == "__main__":
# Note: Running Home Assistant Core programmatically like this is mostly for testing or specific advanced scenarios.
# For typical development, you would create a custom component and run HA via its standard entrypoint.
try:
asyncio.run(run_hass_instance())
except KeyboardInterrupt:
print("Operation interrupted by user.")
hass --version
Debug
Known issues
breakingHome Assistant undergoes monthly releases, often including breaking changes. Users must diligently review release notes and the 'Backward-incompatible changes' section before updating to avoid unexpected issues.fixAlways read the official release notes and breaking changes log before updating. Pay attention to warnings in logs and repair issues in the UI.
affects: All versions (on major/minor updates)
gotchaYAML configuration is crucial for Home Assistant, and incorrect indentation is a leading cause of errors. This can lead to configurations or automations failing silently or behaving unexpectedly.fixUse a linter (e.g., `yamllint`) or a text editor with strong YAML support. Pay close attention to spacing and indentation in configuration files.
affects: All versions
gotchaRunning Home Assistant on an SD card (e.g., on a Raspberry Pi) for extended periods can lead to SD card wear and failure due to frequent write operations (logs, state changes). This can result in data loss or system instability.fixUse more robust storage like an SSD (via USB adapter for Raspberry Pi) or a network-attached storage solution. Ensure regular, automated backups are in place.
affects: All versions
gotchaCustom components are community-maintained and, unlike official integrations, may not receive immediate updates for breaking changes in Home Assistant Core. They can cause instability or break functionality after a core update.fixExercise caution when using custom components. Follow their respective repositories for updates and compatibility information. Report issues to the custom component's maintainer, not Home Assistant Core developers. Minimize their use if stability is paramount.
affects: All versions
gotchaThe `python_script` integration is a sandboxed environment and does not allow arbitrary Python imports. Developers accustomed to full Python scripting often find this limitation restrictive.fixFor advanced scripting with full Python library access, consider using AppDaemon or pyscript integrations instead of `python_script`.
affects: All versions
Errors
Common errors & fixes
Invalid config for [component]:
The Home Assistant configuration (often `configuration.yaml` or related files) contains syntax errors, incorrect indentation, or invalid parameters for a specific integration or platform.
fixUse the Home Assistant 'Configuration validation' tool (Developer Tools > YAML > YAML configuration and click 'Check Configuration') to pinpoint the exact error, then correct the YAML syntax or parameter values.
ModuleNotFoundError: No module named 'homeassistant'
The Python environment where Home Assistant is being executed does not have the `homeassistant` package installed or the execution path is incorrect, often occurring when running custom scripts outside the main Home Assistant process.
fixEnsure Home Assistant is run within its dedicated virtual environment (if applicable) or that the `homeassistant` package is correctly installed and accessible in the Python environment being used. For virtual environments, activate it using `source /path/to/venv/bin/activate` before executing `hass` or any related scripts.
ImportError: cannot import name 'XYZ' from 'homeassistant.components.ABC.const'
This typically occurs after a Home Assistant update where internal module structures, constant names, or helper functions have changed within the core or its components, breaking custom components or older configurations that rely on the previous API.
fixUpdate the custom component or configuration to align with the current Home Assistant API. Check the integration's documentation, Home Assistant release notes, or the custom component's GitHub page for updates and breaking changes relevant to your Home Assistant version.
AttributeError: 'HomeAssistant' object has no attribute 'helpers'
This usually indicates that a method or attribute called on the `HomeAssistant` object (or other core objects) no longer exists in the current Home Assistant version due to API changes, often affecting custom integrations or scripts.
fixReview the Home Assistant developer documentation and the specific integration's changelog for API updates. Update the custom component or script to use the current, valid methods and attributes provided by the Home Assistant core.
Component error: [component_name] - Integration '[component_name]' not found.
Home Assistant cannot locate or load the integration files. This can be due to incorrect placement of custom component files, a typo in the `configuration.yaml`, or issues during the installation/loading process (e.g., via HACS).
fixVerify that the custom component files are in the correct `custom_components` directory (e.g., `/config/custom_components/[component_name]`), ensuring the folder structure and `__init__.py` file are correct. Double-check the integration's name for typos in `configuration.yaml` and restart Home Assistant after making changes.
Upgrade
Version history
2026.8.3latest on PyPI · released Aug 21, 2026
Audit
Dependencies
PythonrequiredHome Assistant Core requires Python 3.14.2 or later to run.