Install ESPHome

ESPHome has two parts: the firmware that runs on your device, and the part that runs on your computer to build and install that firmware. This page is about the second part.

Most people use the ESPHome Device Builder, a dashboard for creating configurations, compiling firmware, and installing it onto devices. You can run it as a Home Assistant app or as a native desktop app on macOS, Windows, and Linux. Both bundle their own Python environment, so there is nothing to install by hand.

If you would rather manage Python yourself, the pip tab covers installing the Device Builder and the ESPHome command-line tool as ordinary Python packages.

Pick your platform below. We’ll try to detect it automatically.

Run ESPHome Device Builder alongside your Home Assistant instance.

Install the official ESPHome Device Builder app:

Clicking the button above opens the ESPHome Device Builder app inside your Home Assistant instance — click Install, then Start, then Open Web UI.

Install Manually

If the button doesn't work, you can install the app by hand:

In Home Assistant, go to Settings → Apps→ Install App.
Find ESPHome Device Builder in the list and click it.
Click Install, then Start, then Open Web UI.

If the app isn't listed, the ESPHome repository hasn't been registered. Click the ⋮ menu (top-right) → Repositories, paste https://github.com/esphome/home-assistant-addon, click Add, then close the dialog and look again.

Run the ESPHome Device Builder dashboard as a Docker container alongside your Home Assistant Container install:

docker run --rm --net=host -v "${PWD}":/config -it ghcr.io/esphome/esphome

Once it's running, open http://localhost:6052 in your browser. --net=host lets the dashboard use mDNS, which it needs to discover devices and to resolve their .local names. On Docker Desktop (where host networking is unavailable) substitute -p 6052:6052; the dashboard still runs, but without mDNS it can only reach devices you give a fixed address.

See Running ESPHome in Docker for image tags, a Compose file, and other options.

Works on Windows 10 and Windows 11.

Download installer (.exe)

Open the downloaded .exe file.
If Windows asks "Do you want to allow this app to make changes?", choose Yes.
Follow the installer prompts.
Launch ESPHome Device Builder from the Start menu.

If you see "Windows protected your PC", click More info → Run anyway.

macOS 10.15 Catalina or newer.

Support for Intel Macs will be removed soon. The Python ecosystem is dropping Intel macOS; the cryptography package no longer publishes Intel builds as of version 49.

Download disk image (.dmg)

Open the downloaded .dmg file.
Drag ESPHome Device Builder into the Applications folder.
Open the Applications folder and double-click ESPHome Device Builder.
The first time you run it, macOS may ask you to confirm — click Open.

Not sure which Mac you have? Click the Apple menu → About This Mac. If you see Apple M1/M2/M3/M4, pick Apple Silicon. If you see Intel, pick Intel.

Choose the package format that matches your distribution.

Download .deb

Double-click the file in your file manager, or run:

sudo apt install ./ESPHome.Device.Builder_*.deb

If serial devices don't show up, add your user to the dialout group and log out and back in: sudo usermod -a -G dialout $USER.

Any operating system with Python 3.12 or newer.

Installing with pip gives you the same tools without the desktop app wrapping them. The web UI and the command-line tool are separate packages, so pick whichever suits you.

Device Builder (Web UI)

The Device Builder needs the ESPHome command-line tool to compile firmware, so install it with the esphome extra to pull in both:

pip install "esphome-device-builder[esphome]"
esphome-device-builder config

Here config is not a subcommand: it is the directory your configurations are stored in, so replace it with whichever path you want to use. The dashboard is then available at http://localhost:6052.

Command Line Only

If you want the command-line tool without the web UI, install esphome on its own:

pip install esphome
esphome run livingroom.yaml

See the getting started guide for a full walkthrough.

Install into a virtual environment if you can. Many Linux distributions now refuse to pip install into the system Python and will fail with externally-managed-environment.

After Installing the Desktop App

The first time you launch ESPHome Device Builder on macOS, Windows, or Linux, it sets up its bundled Python environment in the background and opens the dashboard in your default browser. The ESPHome icon appears in the macOS menu bar, the Windows notification area, or your Linux desktop’s system tray for quick access - open the dashboard, check for updates, or quit from there.

NOTE

Some Linux desktops (notably GNOME without a tray extension) don’t show tray icons at all. The app still runs; use the dashboard in your browser.

Home Assistant users open the dashboard from the Open Web UI button on the app page in Home Assistant.

Building on a Faster Machine

Compiling firmware is the slowest thing the Device Builder does, and on a small host such as a Home Assistant Green or a Raspberry Pi a single build can take several minutes. The Device Builder can hand the compile to another dashboard on your network, such as a desktop or laptop running the desktop app, which builds the firmware and sends it back to be installed as usual. Your devices, configurations, and dashboard all stay where they are; only the build moves.

Pairing the two dashboards is done from Settings on both sides and is documented in the Device Builder README.

Next Steps

With ESPHome installed, head to Getting Started with ESPHome to create your first configuration and install it onto a device.