Installation Guide

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

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

pip install homeassistant

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

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

"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

"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

"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

"SQLAlchemy==2.0.41"        # Database ORM

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

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)

.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

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

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

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

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

"uv==0.10.6"

# Skip all pip installations
hass --skip-pip

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

# 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

# Enable debug logging
export PYTHONDEVMODE=1

# Show asyncio debug warnings
export PYTHONASYNCIODEBUG=1

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

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

# Clear pip cache
pip cache purge

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

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

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

# Fix permissions
chmod -R 755 ~/.homeassistant