Skip to content

Commit 5d99b33

Browse files
authored
Update installing_esphome.rst to mention git for extern. components (#4987)
1 parent ce78b1f commit 5d99b33

File tree

1 file changed

+57
-31
lines changed

1 file changed

+57
-31
lines changed

guides/installing_esphome.rst

Lines changed: 57 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -22,29 +22,39 @@ In the terminal that comes up, check that Python is installed:
2222

2323
.. code-block:: console
2424
25-
> python --version
26-
Python 3.10.1
25+
python --version
2726
28-
.. note::
27+
It should show something like:
2928

30-
Don't copy the ``>``. That's used to show that this is a command that goes
31-
in the console, and to let you see what the expected results are (shown on
32-
the next line without a ``>``)
29+
.. code-block:: console
30+
31+
Python 3.10.1
3332
3433
Looks good? You can go ahead and install ESPHome:
3534

3635
.. code-block:: console
3736
38-
> pip3 install wheel
39-
> pip3 install esphome
37+
pip3 install wheel
38+
pip3 install esphome
4039
4140
And you should be good to go! You can test that things are properly installed
42-
with the following:
41+
with:
42+
43+
.. code-block:: console
44+
45+
esphome version
46+
47+
It should show something like:
4348

4449
.. code-block:: console
4550
46-
> esphome version
47-
Version: 2021.12.3
51+
Version: 2025.5.2
52+
53+
54+
.. note::
55+
56+
You may additionally need to install git for the external components feature.
57+
Download git from `the official link <https://git-scm.com/downloads>`_
4858

4959
Mac
5060
---
@@ -62,24 +72,30 @@ An easy way for installation is via `Homebrew <https://brew.sh/>`_:
6272

6373
.. code-block:: console
6474
65-
$ brew install esphome
75+
brew install esphome
6676
6777
Verify the installation:
6878

6979
.. code-block:: console
7080
71-
$ esphome version
72-
Version: 2024.12.0
81+
esphome version
82+
83+
It should show something like:
84+
85+
.. code-block:: console
86+
87+
Version: 2025.5.2
88+
7389
74-
If you encounter any issues with Homebrew installation, please check the
75-
`ESPHome Homebrew Formula <https://formulae.brew.sh/formula/esphome>`_ page
76-
for additional information.
7790
7891
.. note::
7992

80-
Homebrew may not always provide the latest version immediately. Updating Homebrew will
81-
automatically update ESPHome. If this is ok for you, Homebrew is the easiest way to
82-
install ESPHome.
93+
- If you encounter any issues with Homebrew installation, please check the
94+
`ESPHome Homebrew Formula <https://formulae.brew.sh/formula/esphome>`_ page
95+
for additional information.
96+
- Homebrew may not always provide the latest version immediately. Updating Homebrew will
97+
automatically update ESPHome. If this is ok for you, Homebrew is the easiest way to
98+
install ESPHome.
8399

84100
**pip**
85101

@@ -88,7 +104,7 @@ and may need additional dependencies and path settings. Setting up a virtual env
88104
highly recommended. If you are not familiar with Python virtual environments, Homebrew
89105
may be easier.
90106

91-
You will require Python 3.9 or newer. While your Mac may have a version of Python installed it may not be up-to-date.
107+
You will require Python 3.10 or newer. While your Mac may have a version of Python installed it may not be up-to-date.
92108
Python can be installed from the `official site <https://www.python.org/downloads>`_
93109
or with Homebrew. Once Python is installed, create and activate a virtual environment and install ESPHome with pip:
94110

@@ -110,19 +126,24 @@ Linux
110126
-----
111127

112128
Your distribution probably already has Python installed. Confirm that it is at
113-
least version 3.9:
129+
least version 3.10:
130+
131+
.. code-block:: console
132+
133+
python3 --version
134+
135+
It should show something like:
114136

115137
.. code-block:: console
116138
117-
$ python3 --version
118-
Python 3.9.15
139+
Python 3.10.1
119140
120141
Looks good? Now create a virtual environment to contain ESPHome and it's dependencies.
121142

122143
.. code-block:: console
123144
124-
$ python3 -m venv venv
125-
$ source venv/bin/activate
145+
python3 -m venv venv
146+
source venv/bin/activate
126147
127148
You may or may not see ``(venv)`` at the beginning of your prompt depending on your shell configuration. This indicates that you are in the virtual environment.
128149

@@ -135,22 +156,27 @@ You can go ahead and install ESPHome:
135156
.. caution::
136157

137158
Don't use ``sudo`` with pip. If you do, you'll run into trouble updating
138-
your OS down the road.
159+
your Distro down the road.
139160

140161
For details, see `DontBreakDebian
141162
<https://wiki.debian.org/DontBreakDebian#A.27make_install.27_can_conflict_with_packages>`_.
142163
``pip install`` is equivalent to ``make install`` in this context. The
143164
advice in the article applies to all Linux distributions, not just Debian.
144165

145166
Some people install ESPHome without the virtual environment, which can lead to issues with PATHs etc.
146-
Non virtual environment installations are considered not "supported" as people end up having to know your exact system setup.
167+
Installations without `venv` are considered not "supported" as people end up having to know your exact system setup.
168+
169+
At this point, you should be able to confirm that ESPHome has been successfully installed:
170+
171+
.. code-block:: console
172+
173+
esphome version
147174
148-
At this point, you should be able confirm that ESPHome has been successfully installed:
175+
It should show something like:
149176

150177
.. code-block:: console
151178
152-
$ esphome version
153-
Version: 2022.11.4
179+
Version: 2025.5.2
154180
155181
If you get an error like "Command not found", you need to add the binary to
156182
your ``PATH`` using ``export PATH=$PATH:$HOME/.local/bin``.

0 commit comments

Comments
 (0)