imagegenius/esphome

ESPHome is a system to control your ESP8266/ESP32 by simple yet powerful configuration files and control them remotely through Home Automation systems.

Variants

Pin a specific upstream ESPHome release with the version tag:

ghcr.io/imagegenius/esphome:2026.7.4

Requirements

• Config volume: mount /config for ESPHome projects and generated build data.
• Optional device access: pass USB serial devices through when flashing from the container.

Usage

Docker Compose

---
services:
    esphome:
        image: ghcr.io/imagegenius/esphome:latest
        container_name: esphome
        environment:
            - PUID=1000
            - PGID=1000
            - TZ=Etc/UTC
            - ESPHOME_DASHBOARD_USE_PING=false #optional
        volumes:
            - path_to_appdata:/config
        ports:
            - 6052:6052
        restart: unless-stopped

Parameters

User / Group IDs & umask

Set PUID=1000 PGID=1000 to match volume ownership on the host (id user to find yours). Optionally UMASK=022 (works subtractively, not additively).

Updating

docker pull ghcr.io/imagegenius/esphome:latest
docker stop esphome && docker rm esphome
# recreate with the same docker run parameters
docker image prune  # optional: remove dangling images

Or with compose: docker compose pull && docker compose up -d.

Support

• Issues: https://github.com/imagegenius/docker-esphome/issues
• ESPHome: https://esphome.io/

How this image is built

This repo is built with GitHub Actions, based on the workflow shape from home-operations/containers.

• The container starts from linuxserver/docker-baseimage-alpine.
• ESPHome is installed from the upstream PyPI release, with PlatformIO libraries warmed during build.
• Version and base-image inputs are selected by docker-bake.hcl.
• s6-overlay bits live under root/.
• Renovate tracks ESPHome and build input bumps from the bake annotations.