Installation and Dependencies

How to Install

Global Installation

You will need Python 3.7 or newer installed on your system to use the latest version of esptool.py. If your use case requires Python 2.7, 3.4, 3.5, or 3.6, please use esptool.py v3.3.* instead.

The latest stable esptool release can be installed from PyPI via pip:

$ pip install esptool

With 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 for information about how to access pip.

Setuptools 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.

After 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.

Note

If you actually plan to do development work with esptool itself, see Development Setup for more information.

Virtual Environment Installation

To 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 Flashing Firmware article).

Creating 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:

  • Create a virtual environment and choose its name, e.g. ‘esptoolenv’: python -m venv esptoolenv

  • Activate the virtual environment:

    • On Windows: esptoolenv\Scripts\activate

    • On Linux or MacOS: source esptoolenv/bin/activate

  • Install the latest esptool.py version within the active virtual environment: pip install esptool

  • You can now use it within this virtual environment without affecting your system-wide installations: esptool.py <command>

  • When you’re done using esptool.py, deactivate the virtual environment: deactivate. The environment can be reused by activating it again.

  • If you no longer need the virtual environment, you can remove it by deleting the esptoolenv directory.

How to Update

Standalone

If 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 index is simple:

$ pip install --upgrade esptool

As a Component

If esptool.py is installed as a component of a development framework (e.g. ESP-IDF, Arduino, or PlatformIO), it is advised to follow the update guide of used framework for instructions and not to update the tool directly.

If updating directly is unavoidable, make sure you update to a compatible version by staying on the same MAJOR version number (explained in the 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.

$ pip install esptool==3.3.2

Shell completions

To activate autocompletion, you can manually add commands provided below to your shell’s config file or run them in your current terminal session for one-time activation. You will likely have to restart or re-login for the autocompletion to start working.

bash:

eval "$(register-python-argcomplete esptool.py espsecure.py espefuse.py)"

zsh:

To activate completions in zsh, first make sure compinit is marked for autoload and run autoload:

autoload -U compinit
compinit

Afterwards you can enable completions for esptool.py, espsecure.py and espefuse.py:

eval "$(register-python-argcomplete esptool.py espsecure.py espefuse.py)"

fish:

Not required to be in the config file, only run once

register-python-argcomplete --shell fish esptool.py espsecure.py espefuse.py >~/.config/fish/completions/esptool.py.fish

Other shells nor OS Windows are not supported.