Environment Setup

Set up your development environment for Home Assistant Core

This guide will help you set up a local development environment for Home Assistant Core.

Prerequisites

• Python 3.14.2 or higher - Home Assistant Core requires Python 3.14+
• Git - For cloning the repository and version control
• uv (recommended) - Fast Python package installer

Initial Setup

1. Fork and Clone the Repository

First, fork the home-assistant/core repository on GitHub, then clone your fork:

git clone https://github.com/YOUR_USERNAME/core.git
cd core

Add the upstream repository as a remote:

git remote add upstream https://github.com/home-assistant/core.git

2. Run the Setup Script

Home Assistant provides an automated setup script that configures your development environment:

script/setup

This script will:

• Create VSCode settings from the default template
• Set up a Python virtual environment in .venv
• Install uv if not already present
• Run script/bootstrap to install dependencies
• Install pre-commit hooks with prek
• Generate a default configuration in the config directory
• Configure logging for development

3. Manual Setup (Alternative)

If you prefer manual setup or need more control:

Create a Virtual Environment

# Using uv (recommended)
uv venv .venv
source .venv/bin/activate

# Or using standard Python venv
python3 -m venv .venv
source .venv/bin/activate

Install Dependencies

# Install uv if not present
pip install uv

# Install Home Assistant in editable mode with test dependencies
uv pip install \
  -e . \
  -r requirements_test_all.txt \
  colorlog \
  --upgrade \
  --config-settings editable_mode=compat

Install Pre-commit Hooks

Home Assistant uses pre-commit hooks to ensure code quality:

prek install

Development Tools

Key Dependencies

Your development environment includes:

• pytest - Test framework
• pylint - Python linter with custom Home Assistant plugins
• ruff - Fast Python linter and formatter
• mypy - Static type checker
• prek - Pre-commit hook manager
• coverage - Code coverage measurement

See requirements_test.txt for the complete list.

Pre-commit Hooks

The following hooks run automatically on commit:

• ruff-check - Lints code and fixes issues automatically
• ruff-format - Formats Python code
• codespell - Catches spelling mistakes
• yamllint - Validates YAML files
• prettier - Formats JSON and other files
• mypy - Type checking (for homeassistant/ and pylint/ directories)
• pylint - Custom linting rules (for homeassistant/ and tests/)
• hassfest - Validates integration manifests and metadata

You can run hooks manually:

# Run all hooks on all files
prek run --all-files

# Run specific hook
prek run ruff-check --all-files

Configuration

pyproject.toml

The pyproject.toml file contains all project configuration:

• Build system - Uses setuptools 78.1.1
• Project metadata - Version, dependencies, and URLs
• Tool configuration - pylint, pytest, coverage, ruff settings

Key configuration sections:

[project]
name = "homeassistant"
requires-python = ">=3.14.2"

[tool.pytest.ini_options]
testpaths = ["tests"]
asyncio_mode = "auto"

[tool.ruff]
required-version = ">=0.15.1"

VSCode Settings

The repository includes recommended VSCode settings in .vscode/settings.default.jsonc. The setup script copies this to .vscode/settings.json if it doesn’t exist.

Running Home Assistant

Once your environment is set up, you can run Home Assistant locally:

# Start Home Assistant with config from ./config directory
hass -c config

# Or use the development server script
script/server

Home Assistant will be available at http://localhost:8123.

Troubleshooting

Virtual Environment Issues

If commands aren’t found, ensure your virtual environment is activated:

source .venv/bin/activate

The script/run-in-env.sh wrapper automatically activates the environment:

script/run-in-env.sh mypy homeassistant/

Dependency Conflicts

If you encounter dependency issues:

# Update all dependencies
uv pip install -r requirements_test_all.txt --upgrade

# Check dependency tree
pipdeptree

Pre-commit Hook Failures

If pre-commit hooks fail:

# Run the failing hook directly to see details
prek run pylint --files path/to/file.py

# Skip hooks temporarily (use sparingly)
git commit --no-verify

Next Steps

• Learn about Testing to run and write tests
• Review Code Quality standards
• Read the Contributing Guide before submitting changes
• Check the Developer Documentation for detailed guides