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

Tag	Description	Platforms
latest	Alpine + latest ESPHome app	amd64, arm64

Pin a specific upstream ESPHome release with the version tag:

ghcr.io/imagegenius/esphome:2026.5.1

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

Parameter	Function
-p 6052	WebUI port
-e PUID=1000	UID for permissions — see below
-e PGID=1000	GID for permissions — see below
-e TZ=Etc/UTC	Timezone, see this list
-e ESPHOME_DASHBOARD_USE_PING=false	Use ping instead of mDNS for device status
-v /config	ESPHome config and build data

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.