Skip to content

Update installing_esphome guide for Py install manager #5479

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 2 commits into
base: current
Choose a base branch
from
Draft

Update installing_esphome guide for Py install manager #5479

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4128e6b
Update installing_esphome.md
shvmm Oct 14, 2025
765085f
Update installing_esphome.md
shvmm Oct 14, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 24 additions & 22 deletions content/guides/installing_esphome.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,35 +8,39 @@ title: "Installing ESPHome Manually"
Download Python from [the official site](https://www.python.org/downloads/).

{{< img src="python-win-installer.png"
alt="Python installer window with arrows pointing to \"Add Python to PATH\" and \"Install Now\""
alt="Python installer window with arrows pointing to \"Launch when ready\" and \"Install Python\""
width="75.0%" class="align-center" >}}

Make sure you check "Add Python to PATH", and go all the way through the
installer.
Make sure "Launch when ready" is checked and install.
After the installation is completed, a terminal window will open asking to modify `App execution aliases`, enter `y`.
It will open the app setting window. Make required adjustments as instructed and close the window.
The python install manager should be ready.

Log out and back in, or restart your computer. Whichever is easiest.
Proceed to install supported python runtime v3.13 using `py install 3.13`

Open the start menu and type `cmd`. Press the enter key.
Log out and back in, or restart your computer. Whichever is easiest.

In the terminal that comes up, check that Python is installed:
Open Windows terminal and check whether Python is installed:

```shell
python --version
py install 3.13
python3.13 --version
```

It should show something like:

```shell
Python 3.11.13
```
`Python 3.13.8`

Looks good? You can go ahead and install ESPHome:

```shell
pip3 install wheel
pip3 install esphome
python3.13 -m pip install esphome
```

If you spot pip complaining about PATH / `--no-warn-script-location`,
add the scripts PATH to the user environment variable.
`C:\Users\<username>\AppData\Local\Python\pythoncore-3.13-64\Scripts`

And you should be good to go! You can test that things are properly installed
with:

Expand All @@ -46,13 +50,11 @@ esphome version

It should show something like:

```shell
Version: 2025.8.0
```
`Version: 2025.8.0`

> [!NOTE]
> You may additionally need to install git for the external components feature.
> Download git from [the official link](https://git-scm.com/downloads)
> Download git from [the official link](https://git-scm.com/downloads/win)

## Mac

Expand All @@ -78,9 +80,9 @@ esphome version

It should show something like:

```shell
`
Version: 2025.8.0
```
`

> [!NOTE]
>
Expand Down Expand Up @@ -129,9 +131,9 @@ python3 --version

It should show something like:

```shell
`
Python 3.11.13
```
`

Looks good? Now create a virtual environment to contain ESPHome and it's dependencies.

Expand Down Expand Up @@ -168,9 +170,9 @@ esphome version

It should show something like:

```shell
`
Version: 2025.8.0
```
`

If you get an error like "Command not found", you need to add the binary to
your `PATH` using `export PATH=$PATH:$HOME/.local/bin`.
Expand Down