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 If your use case requires Python 2.7, 3.4, 3.5, or 3.6, please use 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 installed into the default Python executables directory and you should be able to run it with the command or python -m esptool. Please note that probably only python -m esptool will work for Pythons installed from Windows Store.


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

Virtual Environment Installation

To ensure that 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 version within the active virtual environment: pip install esptool

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

  • When you’re done using, 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


If you are using 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 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 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