Setting up a development environment

You need a development environment if you wish to develop ESPHome — new components or otherwise.

In short, ESPHome is set up to use a Python virtual environment.

This guide will walk you through the steps to set up an environment you can use for development.

NOTE

The instructions that follow apply for Linux and macOS. Windows users can still develop ESPHome and its components, but the process is slightly different and covered at the bottom of this guide.

Requirements

• Python 3.11 or newer
• pip (Python package manager)
• Familiarity with git and GitHub

NOTE

ESPHome’s code and documentation is hosted on GitHub; we use this to collaborate on all changes.

As a deep-dive into how git and GitHub works is beyond the scope of this documentation, we’ll assume that you’re already familiar with these tools and just walk through the basic steps required to get started.

If you’re not familiar with git and/or GitHub or if you’d just like more detail on any of the steps that follow, you should read through the GitHub documentation. While there’s a lot there (and it’s consequently probably a bit daunting), if you just want to submit your own work to ESPHome, we might suggest you start with the Fork a repo guide.

Set up the local repository

First you will need a “Fork” of the ESPHome repository. You can do this by visiting the ESPHome repository, clicking the Fork button and following the instructions on GitHub to complete the fork.

Note that forks created from GitHub organization accounts will protect branches involved in pull requests, preventing ESPHome maintainers from making any changes to your branch.

If there is a small change required to a PR to enable it to be approved, a maintainer may well choose to make that change directly rather than leaving a review (this applies particularly to PRs in the docs where a simple formatting fix is needed.)

It is therefore recommended that you use a personal account for forking ESPHome and raising PRs.

Once the fork is created, you can clone the repository to your local machine:

git clone https://github.com/YOUR_GITHUB_USERNAME/NAME_OF_FORK.git
cd NAME_OF_FORK
git remote add upstream https://github.com/esphome/esphome.git

Run the setup script

Once the local clone is set up, you can now run the setup script.

Linux/macOS

script/setup

On Windows with python install manager:

script\setup.bat

This will create a Python virtual environment and install various other requirements.

Activate the virtual environment

To use the virtual environment, you need to activate it. This needs to be done for each new terminal session and is done by running:

Linux/macOS:

source venv/bin/activate

Windows (PowerShell):

venv\Scripts\Activate.ps1

Run esphome

With the virtual environment activated, ESPHome can be run directly from that terminal:

esphome compile some-config-file.yaml

…or:

esphome run some-config-file.yaml --device /dev/tty.your_usb_device

Create your config directory

At this point, it is also good to create an empty directory named config. You should store all of your ESPHome configurations in this directory.

This folder is conveniently listed in the ESPHome .gitignore file, so it will not be added to git.

Create your own working branch

Always do your work in a new branch created from the latest ESPHome upstream dev branch; do not commit changes directly to the dev branch.

git fetch upstream
git checkout -b my-new-feature upstream/dev

This branch should contain your work for this new feature.

After you’ve run the above commands, you’re ready to make (and test!) your changes!

Commit and push your work

Once you’re satisfied with your changes, it’s time to stage and commit them:

git add .
git commit -m "Look mom, I'm contributing to ESPHome!"

After you’ve committed your changes, you can push your branch up to your fork in GitHub:

git push -u origin my-new-feature

Once you’ve pushed your branch, if you wish, you can submit your work for integration into ESPHome.

Windows

Testing Development Changes on Windows

In the examples below:

• username is your GitHub username.
• branch is the branch name you’ve used for your work.

To test changes when using Windows:

• Create a branch in your remote fork of the main ESPHome GitHub repo

• Install from your fork in the same manner you would install ESPHome manually but with one of the following commands:

  pip install --pre https://github.com/username/esphome/archive/branch.zip

  OR

  pip install git+https://github.com/username/esphome.git@branch

• To test changes to the repo without modifying version numbers, a subsequent pip update can be performed using flags --no-deps along with --force-reinstall as follows:

  pip install git+https://github.com/username/esphome.git@branch --no-deps --force-reinstall

  This will ensure that pip only compiles and reinstalls ESPHome and not its dependencies.

• If uv is installed, which can be done using pip install uv, it massively simplifies the above process. UV automagically takes care of all the checks using just one command:

  uv pip install git+https://github.com/username/esphome.git@branch --system

  The --system flag is only necessary when running Python on Windows.