mirror of
https://github.com/esphome/esphome-docs.git
synced 2025-02-28 03:41:57 +01:00
168 lines
5.0 KiB
ReStructuredText
168 lines
5.0 KiB
ReStructuredText
Installing ESPHome Manually
|
|
===========================
|
|
|
|
Windows
|
|
-------
|
|
|
|
Download Python from `the official site <https://www.python.org/downloads/>`_.
|
|
|
|
.. figure:: images/python-win-installer.png
|
|
:align: center
|
|
:width: 75.0%
|
|
:alt: Python installer window with arrows pointing to "Add Python to PATH" and "Install Now"
|
|
|
|
Make sure you check "Add Python to PATH", and go all the way through the
|
|
installer.
|
|
|
|
Log out and back in, or restart your computer. Whichever is easiest.
|
|
|
|
Open the start menu and type ``cmd``. Press the enter key.
|
|
|
|
In the terminal that comes up, check that Python is installed:
|
|
|
|
.. code-block:: console
|
|
|
|
> python --version
|
|
Python 3.10.1
|
|
|
|
.. note::
|
|
|
|
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 ``>``)
|
|
|
|
Looks good? You can go ahead and install ESPHome:
|
|
|
|
.. code-block:: console
|
|
|
|
> pip3 install wheel
|
|
> pip3 install esphome
|
|
|
|
And you should be good to go! You can test that things are properly installed
|
|
with the following:
|
|
|
|
.. code-block:: console
|
|
|
|
> esphome version
|
|
Version: 2021.12.3
|
|
|
|
Mac
|
|
---
|
|
|
|
ESPHome supports macOS. There are several ways to install ESPHome on macOS:
|
|
|
|
- Homebrew
|
|
- pip
|
|
- Cloning the repository
|
|
|
|
|
|
**Homebrew**
|
|
|
|
An easy way for installation is via `Homebrew <https://brew.sh/>`_:
|
|
|
|
.. code-block:: console
|
|
|
|
$ brew install esphome
|
|
|
|
Verify the installation:
|
|
|
|
.. code-block:: console
|
|
|
|
$ esphome version
|
|
Version: 2024.12.0
|
|
|
|
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.
|
|
|
|
**pip**
|
|
|
|
For the latest version, use the pip installation. This may be more difficult to set up
|
|
and may need additional dependencies and path settings. Setting up a virtual environment is
|
|
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.
|
|
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:
|
|
|
|
.. code-block:: console
|
|
|
|
$ python3 -m venv venv # The last argument is the folder in which to install the virtual environment
|
|
$ source venv/bin/activate # For bash or compatible shells. If using a different shell, use activate.csh or activate.fish
|
|
(venv) $ pip install esphome # Installs ESPHome in the virtual environment
|
|
(venv) $ esphome version
|
|
|
|
Any time you want to use ESPHome, you will need to have activated the virtual environment as shown above. When activated you will see ``(venv)`` at the beginning of your prompt.
|
|
|
|
**Cloning the repository**
|
|
|
|
For development purposes of ESPhome cloning the repository is recommended.
|
|
See :ref:`setup_dev_env` for more information on setting up a development environment.
|
|
|
|
Linux
|
|
-----
|
|
|
|
Your distribution probably already has Python installed. Confirm that it is at
|
|
least version 3.9:
|
|
|
|
.. code-block:: console
|
|
|
|
$ python3 --version
|
|
Python 3.9.15
|
|
|
|
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
|
|
|
|
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.
|
|
|
|
You can go ahead and install ESPHome:
|
|
|
|
.. code-block:: bash
|
|
|
|
pip3 install esphome
|
|
|
|
.. caution::
|
|
|
|
Don't use ``sudo`` with pip. If you do, you'll run into trouble updating
|
|
your OS 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.
|
|
|
|
At this point, you should be able confirm that ESPHome has been successfully installed:
|
|
|
|
.. code-block:: console
|
|
|
|
$ esphome version
|
|
Version: 2022.11.4
|
|
|
|
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``.
|
|
|
|
To set this permanently, you can run ``echo 'export
|
|
PATH=$PATH:$HOME/.local/bin' >> $HOME/.bashrc``, then log out and back in.
|
|
|
|
See Also
|
|
--------
|
|
|
|
- :doc:`ESPHome index </index>`
|
|
- :doc:`getting_started_command_line`
|
|
- :doc:`contributing`
|
|
- :ghedit:`Edit`
|