Esptool.py Documentation

This is the documentation for esptool.py - a Python-based, open source, platform independent serial communication tool. Esptool communicates with the ROM bootloader (or flasher stub) in Espressif SoCs. The flasher stub is a small program included with esptool that replaces the original ROM bootloader in the chip to fix some of its limitations and bugs. See Flasher Stub for more details.

esptool.py, espefuse.py and espsecure.py are a complete toolset for working with Espressif chips. They can do a number of things, for example:

  • Read, write, erase, and verify binary data stored in flash.

  • Read chip features and other related data such as MAC address or flash chip ID.

  • Read and write the one-time-programmable eFuses.

  • Prepare binary executable images ready for flashing.

  • Analyze, assemble, and merge binary images.

This document describes using esptool.py with the ESP32 SoC. To switch to a different SoC target, choose target from the dropdown in the upper left.

Quick Start

Getting started is easy:

  1. Install esptool.py:

    $ pip install esptool
    

    For detailed instructions, see How to Install.

  2. Connect an Espressif chip to your computer.

Note

Please note that serial communication has to work and chip has to be in the download mode. This is usually done automatically or can be done manually. Esptool cannot function until this is resolved. For more information, see Troubleshooting.

  1. Run esptool.py commands. For example, to read information about your chip’s SPI flash, run:

    $ esptool.py -p PORT flash_id
    

    Replace PORT with the name of used serial port. If connection fails, see Troubleshooting.

After successfully executing the command, esptool will hard reset the chip, causing it to run the user code. This behavior can be adjusted, see Advanced Options.

Alternatives

esptool.py is not the only tool for working with Espressif chips. Some notable options include:

  • esptool.js is a JavaScript port of esptool.py that can be used in a web browser or in a Node.js environment.

  • espflash is a Rust port of esptool.py. It relies on the support in esp-hal, which may delay support for new chips.

  • OpenOCD is a general-purpose tool for debugging and flashing chips.

Among these, esptool.py is the most feature-rich, and support for the newest chips and features usually appears here first.

More Information