Installation Guide

Detailed installation instructions for Home Assistant Core development.

This guide covers everything you need to install Home Assistant Core for development, including system requirements, dependencies, and various installation methods.

System Requirements

Python Version

Home Assistant Core requires Python 3.14.2 or later. Earlier versions are not supported.

Verify your Python version:

python3 --version
# Should output: Python 3.14.2 or higher

Operating System

Home Assistant Core supports:

• Linux - Recommended for production and development
• macOS (Darwin) - Full support for development
• Windows (WSL) - Use Windows Subsystem for Linux

Native Windows is not supported. The validation code in homeassistant/__main__.py explicitly checks for Linux, macOS, or WSL.

# From homeassistant/__main__.py
def validate_os() -> None:
    """Validate that Home Assistant is running in a supported OS."""
    if not sys.platform.startswith(("darwin", "linux")):
        print(
            "Home Assistant only supports Linux, OSX and Windows using WSL",
            file=sys.stderr,
        )
        sys.exit(1)

Hardware Requirements

Minimum requirements for development:

• CPU: Modern multi-core processor (2+ cores recommended)
• RAM: 2GB minimum, 4GB+ recommended
• Storage: 5GB free space for code and dependencies
• Network: Internet connection for downloading dependencies

Installation Methods

Method 1: Development Installation (Recommended)

This method is best for active development.

1. Clone the Repository

   git clone https://github.com/home-assistant/core.git
   cd core
   
2. Create Virtual Environment

   python3 -m venv venv
   source venv/bin/activate
   

   Virtual environments isolate your Home Assistant installation from system packages, preventing conflicts.

3. Install in Editable Mode

   pip install -e .
   

   The -e flag installs Home Assistant in “editable” mode, meaning changes to the source code take effect immediately without reinstalling.

4. Verify Installation

   hass --version
   # Output: 2026.4.0.dev0
   

Method 2: Using pip (For Testing)

Install the latest release from PyPI:

pip install homeassistant

This method installs the stable release, not the development version. Changes to the source code won’t be reflected.

Method 3: Docker (For Isolation)

Run Home Assistant Core in Docker:

docker run -d \
  --name homeassistant \
  -v /path/to/config:/config \
  -p 8123:8123 \
  ghcr.io/home-assistant/home-assistant:dev

Core Dependencies

Home Assistant Core has numerous dependencies defined in pyproject.toml. Key dependencies include:

Web Framework

"aiohttp==3.13.3"          # Async HTTP server and client
"aiohttp_cors==0.8.1"      # CORS support
"aiohttp-fast-zlib==0.3.0" # Fast compression

Configuration & Validation

"PyYAML==6.0.3"              # YAML parsing
"voluptuous==0.15.2"         # Schema validation
"voluptuous-serialize==2.7.0" # Schema serialization
"annotatedyaml==1.0.2"       # YAML with annotations

Utilities

"Jinja2==3.1.6"              # Template engine
"python-slugify==8.0.4"     # String slugification
"orjson==3.11.5"            # Fast JSON parsing
"awesomeversion==25.8.0"    # Version parsing

Security & Authentication

"PyJWT==2.10.1"             # JSON Web Tokens
"cryptography==46.0.5"      # Cryptographic operations
"bcrypt==5.0.0"             # Password hashing
"pyOpenSSL==25.3.0"         # SSL/TLS support

Database

"SQLAlchemy==2.0.41"        # Database ORM

Network & Discovery

"zeroconf==0.148.0"         # mDNS/DNS-SD discovery
"aiodns==4.0.0"             # Async DNS resolution

The full list of dependencies is automatically installed when you run pip install -e .

Configuration Directory

Home Assistant stores configuration in a dedicated directory.

Default Location

The default configuration directory is determined by get_default_config_dir() in homeassistant/config.py:

def get_default_config_dir() -> str:
    """Put together the default configuration directory based on the OS."""
    data_dir = os.path.expanduser("~")
    return os.path.join(data_dir, CONFIG_DIR_NAME)

Default locations:

• Linux/macOS: ~/.homeassistant
• Custom: Use hass --config /path/to/config

Directory Structure

When Home Assistant starts for the first time, it creates:

.homeassistant/
├── configuration.yaml      # Main configuration file
├── secrets.yaml           # Sensitive data (passwords, tokens)
├── automations.yaml       # Automation definitions
├── scripts.yaml           # Script definitions
├── scenes.yaml            # Scene definitions
├── home-assistant.log     # Application log
├── home-assistant.log.fault # Fault handler log
├── deps/                  # Component dependencies
├── .storage/              # Internal storage (JSON)
└── custom_components/     # User-created integrations

Never commit secrets.yaml to version control. It contains sensitive credentials.

Development Dependencies

For full development capabilities, install additional tools:

Code Quality Tools

# Install pre-commit hooks
pip install pre-commit
pre-commit install

# Install linting tools (defined in pyproject.toml)
pip install pylint ruff mypy

Testing Tools

# Install pytest and related packages
pip install pytest pytest-asyncio pytest-cov

From pyproject.toml:

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

Package Management

Home Assistant uses uv for fast package management:

"uv==0.10.6"

Home Assistant can automatically install integration requirements on startup. Control this with:

# Skip all pip installations
hass --skip-pip

# Skip specific packages
hass --skip-pip-packages "package1,package2"

Use --skip-pip during development to speed up startup time after the initial installation.

Environment Setup

Virtual Environment Best Practices

# Create virtual environment with specific Python version
python3.14 -m venv venv

# Activate on Linux/macOS
source venv/bin/activate

# Activate on Windows WSL
source venv/bin/activate

# Deactivate when done
deactivate

Environment Variables

Useful environment variables for development:

# Enable debug logging
export PYTHONDEVMODE=1

# Show asyncio debug warnings
export PYTHONASYNCIODEBUG=1

# Disable bytecode caching (see changes immediately)
export PYTHONDONTWRITEBYTECODE=1

Installation Verification

Check Installation

Verify your installation is working:

1. Check Version

   hass --version
   # Expected: 2026.4.0.dev0
   
2. Test Imports

   python3 -c "import homeassistant; print(homeassistant.__version__)"
   # Expected: 2026.4.0.dev0
   
3. Check Command Help

   hass --help
   # Should display usage information
   
4. Dry Run

   mkdir -p test_config
   hass --config test_config --version
   rm -rf test_config
   

Command Line Interface

The hass command provides these options (from homeassistant/__main__.py):

usage: hass [-h] [--version] [-c path_to_config_dir] [--recovery-mode]
            [--debug] [--open-ui] [--skip-pip] 
            [--skip-pip-packages package_names] [-v]
            [--log-rotate-days LOG_ROTATE_DAYS] [--log-file LOG_FILE]
            [--log-no-color] [--script ...] [--ignore-os-check]

Home Assistant: Observe, Control, Automate.

options:
  -h, --help            show this help message and exit
  --version             show program's version number and exit
  -c, --config path_to_config_dir
                        Directory that contains the Home Assistant configuration
  --recovery-mode       Start Home Assistant in recovery mode
  --debug               Start Home Assistant in debug mode
  --open-ui             Open the webinterface in a browser
  --skip-pip            Skips pip install of required packages on startup
  --skip-pip-packages package_names
                        Skip pip install of specific packages on startup
  -v, --verbose         Enable verbose logging to file.
  --log-rotate-days LOG_ROTATE_DAYS
                        Enables daily log rotation and keeps up to the specified days
  --log-file LOG_FILE   Log file to write to
  --log-no-color        Disable color logs
  --script ...          Run one of the embedded scripts
  --ignore-os-check     Skips validation of operating system

Troubleshooting

Python Version Issues

Error: “Home Assistant requires at least Python 3.14.2”

Solution: Upgrade Python or use a system with Python 3.14.2+

# Check current version
python3 --version

# Ubuntu/Debian: Use deadsnakes PPA
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.14 python3.14-venv

Operating System Issues

Error: “Home Assistant only supports Linux, OSX and Windows using WSL”

Solution: Install WSL on Windows or use Linux/macOS

# Windows: Install WSL2
wsl --install -d Ubuntu

Dependency Issues

# Clear pip cache
pip cache purge

# Reinstall dependencies
pip install --force-reinstall -e .

# Install specific dependency versions
pip install -r requirements.txt

Permission Issues

# Fix ownership of config directory
sudo chown -R $USER:$USER ~/.homeassistant

# Fix permissions
chmod -R 755 ~/.homeassistant

Next Steps

Now that you have Home Assistant Core installed:

Configuration

Learn how to configure Home Assistant

Quickstart

Follow the quickstart guide to create your first integration

Architecture

Understand Home Assistant’s architecture

Development Checklist

Review the development checklist

Additional Resources

• GitHub Repository
• Developer Documentation
• Community Forum
• Discord Chat