esptool

5.2.0 · active · verified Sun Apr 12

esptool is a Python-based, open-source, platform-independent utility for flashing, provisioning, and interacting with Espressif Systems' SoCs like ESP32 and ESP8266. It facilitates tasks such as reading, writing, erasing, and verifying flash data, alongside functions for reading chip features and preparing binary executable images. The current version is 5.2.0, and the library maintains an active development cycle with frequent updates and major releases.

Warnings

breaking `esptool` v5.0.0 introduced significant breaking changes, including a major refactoring, CLI alterations, and a redesigned public Python API. Existing scripts and workflows from v4.x will likely require updates.
Fix: Consult the official 'v5 Migration Guide' for detailed changes to CLI commands (e.g., removal of `.py` suffix, underscore to dash conversion) and adaptations for the new Python API.
breaking The `image-info` command output format changed, and the `--version` argument was removed in `esptool` v5.0.0. Additionally, the `execute-scripts` command was removed.
Fix: Update any parsing logic for `image-info` output. For custom eFuses scripts, refactor to use `espefuse` as a Python module via its public API.
gotcha The latest `esptool` (v5.x) requires Python 3.10 or newer. Using older Python versions will necessitate installing compatible older `esptool` releases.
Fix: Ensure you are running Python 3.10+. For Python 3.7-3.9, use `esptool` v4.x. For Python 2.7, 3.4-3.6, use `esptool` v3.3.x.
gotcha On some Python installations, `pip install esptool` may fail. Also, direct execution of `esptool.py` might not work in all environments, especially Windows Store Python.
Fix: Try `python -m pip install esptool` or `pip3 install esptool`. If `esptool` commands fail, try `python -m esptool <command>` instead of `esptool <command>`.
gotcha Since `esptool` v5, the recommended command-line invocation no longer uses the `.py` suffix (e.g., `esptool chip_id` instead of `esptool.py chip_id`). The `.py` versions are deprecated.
Fix: Update scripts and command-line invocations to use the suffix-less commands. The `.py` versions are still available for backward compatibility but issue deprecation warnings and will be removed in future major releases.
gotcha Older versions of `esptool` (prior to v5.0.2 and v4.9.1) experienced buffering issues with CP2102 USB-to-UART converters, leading to connection failures.
Fix: Update `esptool` to v5.0.2 or newer, or v4.9.1 or newer, to resolve these buffering issues. [cite: 5.0.2 release notes, 4.9.1 release notes]
gotcha In certain older versions, stub flasher execution with active Secure Boot might fail on ESP32-S3 and ESP32-C3 chips.
Fix: Upgrade `esptool` to v5.0.2 or newer, or v4.9.1 or newer, which includes fixes for secure boot compatibility. [cite: 5.0.2 release notes, 4.9.1 release notes]

Install

pip install esptool Install latest stable version

Imports

esptool
```
import esptool

# Example of using the public API (v5+)
# from esptool import ESPLoader, detect_chip
# loader = detect_chip(port='/dev/ttyUSB0', baud=115200)
```
While `esptool.main()` (or `esptool.py` invoked via `subprocess`) was a common programmatic approach in older versions, it directly writes to stdout. In v5 and later, `esptool` provides a redesigned public Python API for direct programmatic control and better integration with applications.

Quickstart

This command connects to an Espressif chip via the specified serial port, automatically detects its type, and then reads and prints its SPI flash ID. This is a basic way to verify connection and `esptool` functionality.

# To detect an attached Espressif chip and read its flash ID:
# Replace '/dev/ttyUSB0' with your actual serial port (e.g., 'COM1' on Windows)
# Ensure your ESP device is in flashing mode or connected correctly.
esptool --port /dev/ttyUSB0 flash_id

view raw JSON →