1Installation and Dependencies 2============================= 3 4.. _installation: 5 6How to Install 7-------------- 8 9Global Installation 10^^^^^^^^^^^^^^^^^^^ 11 12You will need `Python 3.7 or newer <https://www.python.org/downloads/>`_ installed on your system to use the latest version of ``esptool.py``. 13If your use case requires Python 2.7, 3.4, 3.5, or 3.6, please use ``esptool.py`` v3.3.* instead. 14 15The latest stable esptool release can be installed from `PyPI <https://pypi.org/project/esptool/>`_ via pip: 16 17:: 18 19 $ pip install esptool 20 21With some Python installations this may not work and you’ll receive an error, try ``python -m pip install esptool`` or ``pip3 install esptool``, or consult your `Python installation manual <https://pip.pypa.io/en/stable/installation/>`_ for information about how to access pip. 22 23`Setuptools <https://setuptools.pypa.io/en/latest/userguide/quickstart.html>`_ is also a requirement which is not available on all systems by default. You can install it by a package manager of your operating system, or by ``pip install setuptools``. 24 25After installing, you will have ``esptool.py`` installed into the default Python executables directory and you should be able to run it with the command ``esptool.py`` or ``python -m esptool``. Please note that probably only ``python -m esptool`` will work for Pythons installed from Windows Store. 26 27.. note:: 28 29 If you actually plan to do development work with esptool itself, see :ref:`development-setup` for more information. 30 31Virtual Environment Installation 32^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 33 34To ensure that ``esptool.py`` is used in isolation, and any changes made during its usage won't affect other Python environments or SDK installations, it is advised to install it in a virtual environment and use it directly if possible (more information in the :ref:`flashing` article). 35 36Creating a virtual environment (venv) is a good practice. This is particularly helpful for users who may be concerned about interfering with existing installations (e.g. in an environment of a development-setup framework). Here's a quick guide: 37 38- Create a virtual environment and choose its name, e.g. 'esptoolenv': ``python -m venv esptoolenv`` 39- Activate the virtual environment: 40 41 - On Windows: ``esptoolenv\Scripts\activate`` 42 - On Linux or MacOS: ``source esptoolenv/bin/activate`` 43 44- Install the latest ``esptool.py`` version within the active virtual environment: ``pip install esptool`` 45- You can now use it within this virtual environment without affecting your system-wide installations: ``esptool.py <command>`` 46- When you're done using ``esptool.py``, deactivate the virtual environment: ``deactivate``. The environment can be reused by activating it again. 47- If you no longer need the virtual environment, you can remove it by deleting the ``esptoolenv`` directory. 48 49How to Update 50------------- 51 52Standalone 53^^^^^^^^^^ 54 55If you are using ``esptool.py`` as a standalone tool (as a global installation or in a virtual environment), updating to the latest version released on the `PyPI <https://pypi.org/project/esptool/>`_ index is simple: 56 57:: 58 59 $ pip install --upgrade esptool 60 61As a Component 62^^^^^^^^^^^^^^ 63 64If ``esptool.py`` is installed as a component of a development framework (e.g. `ESP-IDF <https://docs.espressif.com/projects/esp-idf/>`_, `Arduino <https://docs.espressif.com/projects/arduino-esp32/>`_, or `PlatformIO <https://docs.platformio.org/en/latest/platforms/espressif32.html>`_), it is advised to follow the update guide of used framework for instructions and not to update the tool directly. 65 66If updating directly is unavoidable, make sure you update to a compatible version by staying on the same MAJOR version number (explained in the :ref:`versions` article). For instance, if your currently installed ``esptool.py`` is ``v3.3.1``, only update to ``v3.*.*``. You risk introducing incompatible changes by updating to ``v4.*.*`` or higher. 67 68:: 69 70 $ pip install esptool==3.3.2 71 72Shell completions 73----------------- 74 75To activate autocompletion, you can manually add commands provided below to your shell's config file 76or run them in your current terminal session for one-time activation. 77You will likely have to restart or re-login for the autocompletion to start working. 78 79bash: 80:: 81 82 eval "$(register-python-argcomplete esptool.py espsecure.py espefuse.py)" 83 84zsh: 85 86To activate completions in zsh, first make sure `compinit` is marked for 87autoload and run autoload: 88 89.. code-block:: bash 90 91 autoload -U compinit 92 compinit 93 94Afterwards you can enable completions for esptool.py, espsecure.py and espefuse.py: 95 96:: 97 98 eval "$(register-python-argcomplete esptool.py espsecure.py espefuse.py)" 99 100fish: 101 102Not required to be in the config file, only run once 103 104:: 105 106 register-python-argcomplete --shell fish esptool.py espsecure.py espefuse.py >~/.config/fish/completions/esptool.py.fish 107 108Other shells nor OS Windows are not supported. 109