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