{"id":4355,"library":"esptool","title":"esptool","description":"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.","status":"active","version":"5.2.0","language":"en","source_language":"en","source_url":"https://github.com/espressif/esptool/","tags":["esp32","esp8266","flashing","firmware","microcontroller","espressif","serial"],"install":[{"cmd":"pip install esptool","lang":"bash","label":"Install latest stable version"}],"dependencies":[{"reason":"CLI framework","package":"click","optional":false},{"reason":"Configuration handling","package":"pyyaml","optional":false},{"reason":"Binary data manipulation","package":"bitstring","optional":false},{"reason":"Enhanced CLI rendering","package":"rich-click","optional":false},{"reason":"Error correction coding","package":"reedsolo","optional":false},{"reason":"Intel HEX file parsing","package":"intelhex","optional":false},{"reason":"Serial communication with devices","package":"pyserial","optional":false},{"reason":"Encryption and security features","package":"cryptography","optional":false}],"imports":[{"note":"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.","wrong":"import esptool\nesptool.main(['--port', 'COM1', 'chip_id'])","symbol":"esptool","correct":"import esptool\n\n# Example of using the public API (v5+)\n# from esptool import ESPLoader, detect_chip\n# loader = detect_chip(port='/dev/ttyUSB0', baud=115200)"}],"quickstart":{"code":"# To detect an attached Espressif chip and read its flash ID:\n# Replace '/dev/ttyUSB0' with your actual serial port (e.g., 'COM1' on Windows)\n# Ensure your ESP device is in flashing mode or connected correctly.\nesptool --port /dev/ttyUSB0 flash_id","lang":"bash","description":"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."},"warnings":[{"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.","message":"`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.","severity":"breaking","affected_versions":">=5.0.0 (from 4.x)"},{"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.","message":"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.","severity":"breaking","affected_versions":">=5.0.0 (from 4.x)"},{"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.","message":"The latest `esptool` (v5.x) requires Python 3.10 or newer. Using older Python versions will necessitate installing compatible older `esptool` releases.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Try `python -m pip install esptool` or `pip3 install esptool`. If `esptool` commands fail, try `python -m esptool <command>` instead of `esptool <command>`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=5.0.0"},{"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]","message":"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.","severity":"gotcha","affected_versions":"<5.0.2, <4.9.1"},{"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]","message":"In certain older versions, stub flasher execution with active Secure Boot might fail on ESP32-S3 and ESP32-C3 chips.","severity":"gotcha","affected_versions":"<5.0.2, <4.9.1"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}