esptool.py(1)
Download and flash firmware to ESP8266 and ESP32 microcontrollers over serial or network.
Synopsis
esptool.py [OPTIONS] {read_flash,write_flash,read_mac,chip_id,flash_id,erase_flash,version,...} [ARGS]Description
esptool.py is a Python utility for communicating with the bootloader of Espressif ESP8266 and ESP32 microcontrollers. It can download firmware, read/write flash memory, erase flash, read MAC addresses, and perform other low-level chip operations over serial (UART) or network (OTA) interfaces.
The tool supports multiple chip variants and flash modes, making it essential for firmware development, testing, and deployment workflows. It automatically detects chip type and uses appropriate flash parameters.
Common options
| Flag | What it does |
|---|---|
-p, --port PORT | Serial port device (e.g., /dev/ttyUSB0, COM3); default is auto-detect |
-b, --baud BAUD | Serial port baud rate; default 460800, use lower values for unreliable connections |
--chip {esp8266,esp32,esp32s2,esp32s3,esp32c3,...} | Explicitly specify chip type instead of auto-detection |
-e, --erase-all | Erase entire flash memory before writing |
--flash_mode {qio,qout,dio,dout} | Flash read/write mode; default is dio for ESP32, qio for ESP8266 |
--flash_size {2MB,4MB,8MB,16MB,32MB,64MB,128MB} | Flash chip size; use 'keep' to preserve existing value |
--flash_freq {40m,80m,120m,160m,240m} | Flash clock frequency; default 40MHz |
-v, --verbose | Increase output verbosity; use multiple times (-vv, -vvv) for more detail |
--before {default,usb_reset,hard_reset,no_reset,rts} | Reset behavior before flashing; default is 'default' |
--after {hard_reset,soft_reset,no_reset} | Reset behavior after flashing; default is 'hard_reset' |
--no-progress | Disable progress bar during operations |
Examples
Flash firmware.bin to address 0x0 on ESP device connected to /dev/ttyUSB0
esptool.py -p /dev/ttyUSB0 write_flash 0x0 firmware.binErase flash and write app at 0x1000 and partition table at 0x8000 at high baud rate
esptool.py -p /dev/ttyUSB0 -b 921600 -e write_flash 0x1000 app.bin 0x8000 partitions.binRead the MAC address of the connected ESP device
esptool.py -p /dev/ttyUSB0 read_macDisplay chip ID and other chip identification information
esptool.py -p /dev/ttyUSB0 chip_idErase the entire flash memory on the device
esptool.py -p /dev/ttyUSB0 erase_flashRead 1MB of flash starting at address 0x0 and save to dump.bin
esptool.py -p /dev/ttyUSB0 read_flash 0x0 0x100000 dump.binFlash ESP32 in DIO mode with explicit chip specification and compression enabled
esptool.py --chip esp32 -p /dev/ttyUSB0 --flash_mode dio --flash_freq 80m write_flash -z 0x1000 bootloader.binPrint esptool and target firmware version information
esptool.py -p /dev/ttyUSB0 version