Skip to content

Update installing_esphome.rst to mention git for extern. components #4987

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.

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

Open
wants to merge 8 commits into
base: current
Choose a base branch
from
Open
Changes from all commits
Commits
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
88 changes: 57 additions & 31 deletions guides/installing_esphome.rst
Original file line number Diff line number Diff line change
Expand Up @@ -22,29 +22,39 @@ In the terminal that comes up, check that Python is installed:

.. code-block:: console

> python --version
Python 3.10.1
python --version

.. note::
It should show something like:

Don't copy the ``>``. That's used to show that this is a command that goes
in the console, and to let you see what the expected results are (shown on
the next line without a ``>``)
.. code-block:: console

Python 3.10.1

Looks good? You can go ahead and install ESPHome:

.. code-block:: console

> pip3 install wheel
> pip3 install esphome
pip3 install wheel
pip3 install esphome

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

.. code-block:: console

esphome version

It should show something like:

.. code-block:: console

> esphome version
Version: 2021.12.3
Version: 2025.5.2


.. note::

You may additionally need to install git for the external components feature.
Download git from `the official link <https://git-scm.com/downloads>`_

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

.. code-block:: console

$ brew install esphome
brew install esphome

Verify the installation:

.. code-block:: console

$ esphome version
Version: 2024.12.0
esphome version

It should show something like:

.. code-block:: console

Version: 2025.5.2


If you encounter any issues with Homebrew installation, please check the
`ESPHome Homebrew Formula <https://formulae.brew.sh/formula/esphome>`_ page
for additional information.

.. note::

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

**pip**

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

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.
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.
Python can be installed from the `official site <https://www.python.org/downloads>`_
or with Homebrew. Once Python is installed, create and activate a virtual environment and install ESPHome with pip:

Expand All @@ -110,19 +126,24 @@ Linux
-----

Your distribution probably already has Python installed. Confirm that it is at
least version 3.9:
least version 3.10:

.. code-block:: console

python3 --version

It should show something like:

.. code-block:: console

$ python3 --version
Python 3.9.15
Python 3.10.1

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

.. code-block:: console

$ python3 -m venv venv
$ source venv/bin/activate
python3 -m venv venv
source venv/bin/activate

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.

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

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

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

Some people install ESPHome without the virtual environment, which can lead to issues with PATHs etc.
Non virtual environment installations are considered not "supported" as people end up having to know your exact system setup.
Installations without `venv` are considered not "supported" as people end up having to know your exact system setup.

At this point, you should be able to confirm that ESPHome has been successfully installed:

.. code-block:: console

esphome version

At this point, you should be able confirm that ESPHome has been successfully installed:
It should show something like:

.. code-block:: console

$ esphome version
Version: 2022.11.4
Version: 2025.5.2

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