> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/home-assistant/core/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Warning>
  Home Assistant Core requires **Python 3.14.2 or later**. Earlier versions are not supported.
</Warning>

Verify your Python version:

```bash theme={null}
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

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

```python theme={null}
# 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.

<Steps>
  <Step title="Clone the Repository">
    ```bash theme={null}
    git clone https://github.com/home-assistant/core.git
    cd core
    ```
  </Step>

  <Step title="Create Virtual Environment">
    ```bash theme={null}
    python3 -m venv venv
    source venv/bin/activate
    ```

    <Tip>
      Virtual environments isolate your Home Assistant installation from system packages, preventing conflicts.
    </Tip>
  </Step>

  <Step title="Install in Editable Mode">
    ```bash theme={null}
    pip install -e .
    ```

    The `-e` flag installs Home Assistant in "editable" mode, meaning changes to the source code take effect immediately without reinstalling.
  </Step>

  <Step title="Verify Installation">
    ```bash theme={null}
    hass --version
    # Output: 2026.4.0.dev0
    ```
  </Step>
</Steps>

### Method 2: Using pip (For Testing)

Install the latest release from PyPI:

```bash theme={null}
pip install homeassistant
```

<Note>
  This method installs the stable release, not the development version. Changes to the source code won't be reflected.
</Note>

### Method 3: Docker (For Isolation)

Run Home Assistant Core in Docker:

```bash theme={null}
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

```toml theme={null}
"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

```toml theme={null}
"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

```toml theme={null}
"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

```toml theme={null}
"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

```toml theme={null}
"SQLAlchemy==2.0.41"        # Database ORM
```

### Network & Discovery

```toml theme={null}
"zeroconf==0.148.0"         # mDNS/DNS-SD discovery
"aiodns==4.0.0"             # Async DNS resolution
```

<Info>
  The full list of dependencies is automatically installed when you run `pip install -e .`
</Info>

## 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`:

```python theme={null}
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
```

<Warning>
  Never commit `secrets.yaml` to version control. It contains sensitive credentials.
</Warning>

## Development Dependencies

For full development capabilities, install additional tools:

### Code Quality Tools

```bash theme={null}
# 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

```bash theme={null}
# Install pytest and related packages
pip install pytest pytest-asyncio pytest-cov
```

From `pyproject.toml`:

```toml theme={null}
[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:

```toml theme={null}
"uv==0.10.6"
```

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

```bash theme={null}
# Skip all pip installations
hass --skip-pip

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

<Tip>
  Use `--skip-pip` during development to speed up startup time after the initial installation.
</Tip>

## Environment Setup

### Virtual Environment Best Practices

```bash theme={null}
# 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:

```bash theme={null}
# 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:

<Steps>
  <Step title="Check Version">
    ```bash theme={null}
    hass --version
    # Expected: 2026.4.0.dev0
    ```
  </Step>

  <Step title="Test Imports">
    ```bash theme={null}
    python3 -c "import homeassistant; print(homeassistant.__version__)"
    # Expected: 2026.4.0.dev0
    ```
  </Step>

  <Step title="Check Command Help">
    ```bash theme={null}
    hass --help
    # Should display usage information
    ```
  </Step>

  <Step title="Dry Run">
    ```bash theme={null}
    mkdir -p test_config
    hass --config test_config --version
    rm -rf test_config
    ```
  </Step>
</Steps>

## Command Line Interface

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

```bash theme={null}
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

<Warning>
  **Error**: "Home Assistant requires at least Python 3.14.2"

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

  ```bash theme={null}
  # 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
  ```
</Warning>

### Operating System Issues

<Warning>
  **Error**: "Home Assistant only supports Linux, OSX and Windows using WSL"

  **Solution**: Install WSL on Windows or use Linux/macOS

  ```bash theme={null}
  # Windows: Install WSL2
  wsl --install -d Ubuntu
  ```
</Warning>

### Dependency Issues

```bash theme={null}
# Clear pip cache
pip cache purge

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

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

### Permission Issues

```bash theme={null}
# 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:

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="/configuration">
    Learn how to configure Home Assistant
  </Card>

  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Follow the quickstart guide to create your first integration
  </Card>

  <Card title="Architecture" icon="sitemap" href="https://developers.home-assistant.io/docs/architecture_index">
    Understand Home Assistant's architecture
  </Card>

  <Card title="Development Checklist" icon="list-check" href="https://developers.home-assistant.io/docs/development_checklist">
    Review the development checklist
  </Card>
</CardGroup>

## Additional Resources

* [GitHub Repository](https://github.com/home-assistant/core)
* [Developer Documentation](https://developers.home-assistant.io/)
* [Community Forum](https://community.home-assistant.io/)
* [Discord Chat](https://www.home-assistant.io/join-chat/)