Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/esphome/esphome.io/llms.txt

Use this file to discover all available pages before exploring further.

ESPHome can be installed in three ways: via pip (Python’s package manager) on Windows, macOS, and Linux; via Docker for a self-contained, dependency-free environment; or as a Home Assistant add-on for the simplest possible setup. Choose the method that fits your workflow — the end result and feature set are identical across all three.

​
System Requirements

RequirementMinimumNotes
Python3.11+3.11 or newer required
pipbundled with PythonUsed to install ESPHome and dependencies
RAM512 MB1 GB+ recommended for compiling
Disk2 GB freePlatformIO toolchain is downloaded on first build
OSWindows 10+, macOS 12+, LinuxAny reasonably modern distribution
ESPHome requires Python 3.11 or newer. Check your version with python3 --version before installing.

​
Install via pip

# 1. Confirm Python version
python3 --version  # Should print Python 3.11 or newer

# 2. Create a virtual environment
python3 -m venv venv

# 3. Activate the virtual environment
source venv/bin/activate

# 4. Install ESPHome
pip3 install esphome

# 5. Verify the installation
esphome version
A successful install prints something like: 
Version: 2025.8.0

​
Using a Virtual Environment

Using a Python virtual environment (venv) is strongly recommended on all platforms. It keeps ESPHome and its dependencies isolated from your system Python, avoids permission issues, and makes it easy to upgrade or remove ESPHome without affecting other tools. 
# Create the environment (only once)
python3 -m venv venv

# Activate it (every new terminal session)
source venv/bin/activate       # Linux / macOS bash/zsh
# source venv/bin/activate.fish  # fish shell
# source venv/bin/activate.csh   # csh/tcsh
# venv\Scripts\activate.bat      # Windows CMD
# venv\Scripts\Activate.ps1      # Windows PowerShell

# You'll see (venv) in your prompt when active
(venv) $ pip install esphome
(venv) $ esphome version
Do not run pip install with sudo on Linux. Doing so installs packages into the system Python and can cause conflicts when your distribution’s package manager updates Python. Always use a venv or a user-level install. See DontBreakDebian for details (the advice applies to all Linux distributions).
If you get a command not found error after installing, your local bin directory may not be on PATH: 
export PATH=$PATH:$HOME/.local/bin

# To make this permanent:
echo 'export PATH=$PATH:$HOME/.local/bin' >> ~/.bashrc

​
Install via Docker

The official ESPHome Docker image (ghcr.io/esphome/esphome) bundles ESPHome and all its dependencies — no Python setup required. It supports AMD64, ARM, and ARM64 (AArch64) architectures. 
# Pull the latest stable image
docker pull ghcr.io/esphome/esphome

# Verify
docker run --rm ghcr.io/esphome/esphome version

​
Docker Image Tags

TagPoints toRecommended use
latest / stableLatest stable releaseManual, one-off pulls
YEAR.MONTH (e.g., 2024.12)Latest patch in that release seriesRecommended for auto-updates — no breaking changes within a series
betaLatest beta, or latest stable when no beta existsTesting upcoming features
devDaily build from the dev branchDevelopment and cutting-edge testing
Avoid auto-updating containers pinned to latest or stable. ESPHome releases occasionally include breaking changes between major versions. Pin to a YEAR.MONTH tag and update manually after reviewing the release notes.

​
Docker Run (one-off commands)

# Run the setup wizard
docker run --rm -v "${PWD}":/config -it ghcr.io/esphome/esphome wizard livingroom.yaml

# Compile and flash via USB on Linux
docker run --rm --privileged \
  -v "${PWD}":/config \
  --device=/dev/ttyUSB0 \
  -it ghcr.io/esphome/esphome run livingroom.yaml

# Stream logs wirelessly
docker run --rm -v "${PWD}":/config -it ghcr.io/esphome/esphome logs livingroom.yaml

​
Docker Compose

For a persistent ESPHome Device Builder service, use Docker Compose: 
# docker-compose.yml
services:
  esphome:
    container_name: esphome
    image: ghcr.io/esphome/esphome:2024.12   # Pin to a release series
    volumes:
      - /path/to/esphome/config:/config
      - /etc/localtime:/etc/localtime:ro
    restart: always
    privileged: true
    network_mode: host
    environment:
      - USERNAME=admin
      - PASSWORD=ChangeMe
Start with docker compose up -d, then open http://<your-host>:6052.
Running ESPHome in Docker on WSL2 can be 10× slower than native Linux when your config files live on a Windows-mounted drive (e.g., /mnt/c/...). Store your ESPHome configs inside the WSL2 filesystem instead — for example at ~/esphome/config — to get native filesystem performance. See esphome#12568 for more context.
If you back your Docker config volume with an NFS share, mount it with the nolock option. Without it, PlatformIO (the underlying build system) may hang on startup. See platformio-core#3089.

​
Install as a Home Assistant Add-on

If you run Home Assistant OS or Home Assistant Supervised, the ESPHome Device Builder is available as a native add-on with one-click install: Open ESPHome add-on in Home Assistant Or install it manually:
1

Open Add-on Store

In Home Assistant, go to Settings → Add-ons → Add-on Store.
2

Find ESPHome Device Builder

Search for ESPHome Device Builder in the store search box.
3

Install and Start

Click the add-on, then click Install. Once installed, enable Start on boot and Watchdog, then click Start.
4

Open the Web UI

Click Open Web UI to launch the ESPHome Device Builder dashboard.
For a complete walkthrough of using the add-on to create and flash your first device, see the Home Assistant Getting Started guide.

​
Verifying Your Installation

Regardless of installation method, you should be able to run: 
esphome version
And see output like: 
Version: 2025.8.0
If the command is not found after a pip install, ensure your virtual environment is activated or add ~/.local/bin to your PATH.

​
Updating ESPHome

# Activate your virtual environment first
source venv/bin/activate

pip install --upgrade esphome
esphome version

​
Where to Go Next

Build docs developers (and LLMs) love

Get started for freeTalk to us