Blog
esptool: Commands, Flags, Fixes
esptool is the tool every ESP32 owner ends up running by hand eventually — the Arduino IDE hides it, PlatformIO hides it, and then one day flashing fails and you are typing Python into a terminal. Commands, flags, and the errors that make no sense until you have seen them once.
What is esptool?
esptool is Espressif’s official command-line tool for talking to ESP32 chips over serial — flashing, erasing, reading memory, pulling identity. Every flashing path funnels through it: the Arduino IDE bundles it, PlatformIO bundles it, web installers run it. Knowing it is the debugging hour you never repeat.
How Do I Check That esptool Is Installed?
Run esptool.py version. A version number (5.x, 4.7, whatever is current) means you are set. “Command not found” means pip install esptool — Python 3.7+ is the only requirement.
What Are the Most Useful esptool Commands?
The core esptool commands are five: chip_id identifies the chip, flash_id reads the flash, read_mac prints the factory MAC, erase_flash wipes everything, and write_flash writes a binary at an address — 90% of daily use. merge_bin combines several binaries into one image to hand to someone else.
How Do I Flash Firmware With esptool?
One line does it: esptool.py write_flash 0x0 firmware.bin, with --port COM3 added on most machines. The offset matters more than people think: 0x0 is where a factory image starts, while ESP-IDF apps go to 0x10000. Flash at the wrong offset and the board boots to nothing, which is how many “bricked” boards turn out to be misflashed ones. The flashing FAQ covers offsets and partition layouts.
How Do I Erase the ESP32 Flash?
esptool.py erase_flash wipes the whole chip in seconds. The warning everyone skips: it removes the bootloader too, so a board that ran stock firmware will not boot until you flash something back. Erasing fixes a corrupted partition table and boot-loops — treat it as a reset, not a repair.
Can I Back Up the Flash Before Messing With It?
esptool.py read_flash 0x0 0x400000 backup.bin dumps the first 4 MB to a file — the standard panic-before-upgrade move; restoring is write_flash at the same offset. One caveat: a plain backup will not restore onto a board with flash encryption enabled — I learned that the hard way last spring.
What Do –port, –baud, and the Other Flags Do?
--port picks the serial port (COM3 on Windows, /dev/ttyUSB0 on Linux, /dev/cu.usbserial-XXXX on macOS); --baud sets speed — 460800 is a safe fast pick, and some USB chips stutter above 921600, so it depends on your board’s bridge chip; --chip forces the target if auto-detection fails. The rest you can ignore until an error names one.
Why Do I Get “Failed to Connect to ESP32: Timed Out Waiting for Packet Header”?
The chip is not in boot mode. esptool needs the ROM bootloader listening, and the classic causes are: an auto-reset circuit that is not wired (bare modules), the wrong port, or something else holding the serial line — I once chased this exact error for an hour because the Serial Monitor was still open. Hold BOOT, tap EN, release BOOT, retry. On bare modules, tie GPIO0 to ground at power-on. The debugging FAQ has more.
Why Does Flashing Hang at 100%?
The data is written and the board resets into the new firmware, staying silent — normal when the firmware has no serial output. A boot loop instead means the image targets the wrong flash size or chip. Confirm with esptool.py chip_id, check flash_id, re-flash.
Does esptool Work the Same on Windows, Linux, and Mac?
Yes — same commands, flags, and offsets, because it is a Python script on every platform. Only port naming and drivers differ; our KB has the driver notes for each OS.
Rehearse What esptool Will Flash
esptool’s job is putting a binary on silicon; our job is making sure that binary is worth flashing. Every example here builds with arduino-cli — the same ecosystem this FAQ’s flags configure — so the compile-verify loop can run in a tab (start with blink) while the erase/write/download-mode flags stay reserved for real hardware day.