Skip to content

Installation

This guide will walk you through installing HAEO on your Home Assistant instance.

Prerequisites

Before installing HAEO, ensure you have:

  • Home Assistant version 2025.4.4 or newer
  • HACS (Home Assistant Community Store) installed (recommended)

HACS provides automatic updates and easy installation.

Step 1: Add Custom Repository

  1. Open your Home Assistant instance
  2. Navigate to HACS → Integrations
  3. Click the three dots (⋮) in the top right corner
  4. Select Custom repositories
  5. Add the following details:
    • Repository: https://github.com/ha-energy-optimiser/haeo
    • Category: Integration
  6. Click Add

Step 2: Install HAEO

  1. In HACS, search for HAEO or Home Assistant Energy Optimization
  2. Click on the integration
  3. Click Download
  4. Select the latest version
  5. Click Download again to confirm

Step 3: Restart Home Assistant

After installation, restart Home Assistant:

  1. Navigate to Settings → System
  2. Click Restart
  3. Wait for Home Assistant to complete the restart before proceeding

If you need a refresher on the restart process, see the Home Assistant restart documentation.

Method 2: Manual Installation

If you prefer not to use HACS or need manual control:

Step 1: Download HAEO

  1. Visit the releases page
  2. Download the latest haeo.zip file
  3. Extract the archive

Step 2: Copy Files

  1. Connect to your Home Assistant instance (via SSH, Samba, or file editor)
  2. Navigate to your Home Assistant config directory (usually /config)
  3. If it doesn't exist, create a custom_components directory
  4. Copy the haeo folder from the archive into custom_components

Your directory structure should look like:

config/
├── custom_components/
│   └── haeo/
│       ├── __init__.py
│       ├── manifest.json
│       ├── config_flow.py
│       └── ... (other files)
└── configuration.yaml

Step 3: Restart Home Assistant

Restart Home Assistant as described in the HACS installation section.

Verify Installation

After restarting, verify HAEO is installed correctly:

  1. Navigate to Settings → Devices & Services
  2. Click Add Integration (+ button in bottom right)
  3. Search for HAEO or Home Assistant Energy Optimization

If HAEO appears in the list, the installation was successful!

Updating HAEO

Via HACS

  1. Open HACS → Integrations
  2. Find HAEO in your installed integrations
  3. If an update is available, click Update
  4. Restart Home Assistant

Manual Update

  1. Download the latest release
  2. Replace the custom_components/haeo directory with the new version
  3. Restart Home Assistant

Breaking Changes

Always check the release notes before updating. Pay special attention to major version changes. Some updates may require configuration adjustments.

See the troubleshooting page for help with common installation issues.

Uninstalling HAEO

Remove the Integration

  1. Navigate to Settings → Devices & Services
  2. Find the HAEO integration
  3. Click the three dots (⋮) next to it
  4. Select Delete
  5. Confirm deletion

Remove Files

Via HACS:

  1. Open HACS → Integrations
  2. Find HAEO
  3. Click the three dots (⋮)
  4. Select Remove
  5. Restart Home Assistant

Manual removal:

  1. Delete the custom_components/haeo directory
  2. Restart Home Assistant

Next Steps

Move on to these topics once the integration is installed.

  • Configure your first network

    Create your hub, add elements, and establish energy flow connections.

    Configuration guide

  • Check optimization outputs

    Learn how to read HAEO sensors and verify results after setup.

    Optimization overview

  • Troubleshoot installation issues

    Resolve common installation and startup problems quickly.

    Troubleshooting tips