Environment Setup

​

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

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

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

​

2. Run the Setup Script

script/setup

• 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)

​

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

prek install

​

Development Tools

​

Key Dependencies

• 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

​

Pre-commit Hooks

• 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

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

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

​

Configuration

​

pyproject.toml

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

[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

​

Running Home Assistant

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

# Or use the development server script
script/server

​

Troubleshooting

​

Virtual Environment Issues

source .venv/bin/activate

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

​

Dependency Conflicts

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

# Check dependency tree
pipdeptree

​

Pre-commit Hook Failures

# 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