esptool

library5.3.1pypypi✓ verified 24d ago

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.

devops http-networking serialization

pip install esptool

github ↗package ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · ESPTOOL

esptool

devopspythonv5.3.1

Install

6.8s avg

Import

172ms

Disk

57MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v5.3.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.178s · 59.5MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 6.8s · import 0.166s · 60MB

57MB installed

● package 57MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

esptool

✓ import esptool # Example of using the public API (v5+) # from esptool import ESPLoader, detect_chip # loader = detect_chip(port='/dev/ttyUSB0', baud=115200)

✗ import esptool esptool.main(['--port', 'COM1', 'chip_id'])

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.

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

esptool.py --version

Debug

Known issues

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.

affects: >=5.0.0 (from 4.x)

breakingThe `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.

affects: >=5.0.0 (from 4.x)

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

affects: All versions

gotchaOn 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>`.

affects: All versions

gotchaSince `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.

affects: >=5.0.0

gotchaOlder 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]

affects: <5.0.2, <4.9.1

gotchaIn 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]

affects: <5.0.2, <4.9.1

Errors

Common errors & fixes

A fatal error occurred: Failed to connect to ESP32: Timed out waiting for packet header

This error often indicates that the ESP32/ESP8266 chip is not entering download mode correctly, cannot communicate with esptool, or there are fundamental connectivity issues.

fix

Ensure the ESP board is correctly wired and powered. Manually put the board into download mode by holding the BOOT (or FLASH) button, pressing and releasing the RESET (or EN) button, then releasing the BOOT button when esptool attempts to connect. Check USB cable quality, ensure correct serial port drivers are installed, and verify the correct serial port is selected in the command (e.g., `esptool.py -p COMx ...`).

'esptool.py' is not recognized as an internal or external command, operable program or batch file.

The esptool executable or script is not found in the system's PATH environment variable, or it's being called incorrectly.

fix

If installed via `pip`, try running `esptool` instead of `esptool.py`. Alternatively, invoke it using `python -m esptool` or provide the full path to the `esptool.py` script. Ensure Python and pip are correctly installed and added to your system's PATH.

A fatal error occurred: Failed to connect to ESP32: Invalid head of packet (0xXX)

This error suggests corruption or noise on the serial communication lines, often due to a poor quality USB cable, insufficient power supply to the ESP module, or interference on the data lines, or the chip is not in the correct boot mode.

fix

Try a different, high-quality USB cable. Ensure the ESP board receives stable and sufficient power (e.g., use an external power supply or a powered USB hub). Disconnect any unnecessary peripherals from the ESP's GPIO pins that might interfere with flashing. Try lowering the baud rate with the `-b` option (e.g., `esptool.py --baud 115200 ...`).

A fatal error occurred: Could not open /dev/ttyUSB0, the port doesn't exist

The specified serial port does not exist, the USB-to-serial driver is not installed, or the user lacks the necessary permissions to access the serial port.

fix

Verify the correct serial port name (e.g., `COMx` on Windows, `/dev/ttyUSBx` or `/dev/ttyACMx` on Linux/macOS). Install the appropriate USB-to-serial drivers (e.g., for CH340, CP210x, FTDI chips). On Linux, add your user to the `dialout` (or `uucp` on Arch-based systems) group using `sudo usermod -a -G dialout $USER` and then log out and back in for changes to take effect.

serial.serialutil.SerialException: [Errno 13] Permission denied: '/dev/ttyUSB0'

The current user lacks read/write permissions for the specified serial port, or another process is currently using the port.

fix

On Linux, add your user to the `dialout` group (`sudo usermod -a -G dialout $USER`) and log out/in; on Windows, ensure no other application is using the COM port.

Upgrade

Version history

5.3.1latest on PyPI · released Jun 29, 2026

Audit

Dependencies

clickrequiredCLI framework

pyyamlrequiredConfiguration handling

bitstringrequiredBinary data manipulation

rich-clickrequiredEnhanced CLI rendering

reedsolorequiredError correction coding

intelhexrequiredIntel HEX file parsing

pyserialrequiredSerial communication with devices