esptool.py Guide: Install, Flash, Erase & Backup ESP32 Firmware

If you've ever uploaded firmware to an ESP32 board using the Arduino IDE, ESPHome, PlatformIO, or MicroPython, chances are that esptool.py was working behind the scenes.

What is esptool.py? #

esptool.py is an open-source command-line tool developed by Espressif for ESP32 and ESP8266 chips. It handles flashing firmware, erasing flash, reading backups, and low-level hardware operations - and runs silently behind Arduino IDE, ESPHome, and PlatformIO every time you upload code.

Use esptool.py directly when you need to:

Many ESP32 boards use different USB-to-UART bridge chips (CP210x, CH340) - esptool.py lets you set the correct baud rate and port when defaults fail. More about USB-to-UART bridges →

Setting Up esptool.py #

Install esptool.py on Windows, macOS, or Linux in three steps.

brew install esptool

sudo apt install python3 python3-pip

python3 --version

pip install esptool

esptool.py version

python -m esptool version

Flashing Your ESP32 with esptool.py for the First Time #

With esptool.py installed, here's the full process to flash ESP32 firmware from the command line.

1 Connect Your ESP32

Use a USB cable to connect your ESP32 development board to your computer.

Important: Make sure the cable supports data transfer - many micro-USB cables are power-only.

2 Identify the Serial Port

Find which serial port your ESP32 is connected to:

Windows

Command Prompt:

wmic path Win32_SerialPort get DeviceID,Name

Or use Device Manager → Ports (COM & LPT)

Look for: COM3, COM4, etc.

macOS

Terminal:

ls /dev/tty.*

Look for: /dev/tty.usbmodemXXXX

Linux

Terminal:

ls /dev/ttyUSB*

Look for: /dev/ttyUSB0

ESP32 not detected? Install USB-to-Serial drivers:

• CP210x (Silicon Labs): Download here

• CH340 (WCH): Download here

See also: ESP32 USB-to-UART bridge guide.

3 Erase Flash Memory (optional but recommended)

Erase existing flash to prevent conflicts with new firmware:

esptool.py --port <your-port> erase_flash

Replace <your-port> with your serial port (e.g., /dev/ttyUSB0 or COM3).

Expected: Chip erase completed successfully in 2.5s. Hold the BOOT/FLASH button if it can't connect; release once erase starts.

4 Flash the Firmware

Have your firmware.bin ready, then run:

esptool.py --chip esp32 --port <your-port> --baud 460800 write_flash -z 0x1000 firmware.bin

Flag reference:

--chip esp32 - Target chip (esp32, esp32s3, esp32c3, …)

--port <your-port> - Serial port (e.g., COM3, /dev/ttyUSB0)

--baud 460800 - Baud rate; reduce to 115200 if errors occur

write_flash -z 0x1000 - Write binary at flash offset 0x1000

Expected: Hash of data verified. / Leaving... / Hard resetting via RTS pin...

Where to get ESP32 firmware:

• WLED - LED control firmware

• ESPHome - Smart home automation

• MicroPython - Python on ESP32

• Tasmota - MQTT automation

• Arduino IDE - Custom firmware

Download the correct .bin for your ESP32 chip variant.

Your ESP32 is now flashed and ready to go!

Essential Commands #

Download full-resolution cheatsheet (PNG) →

Quick reference for the most common esptool.py commands. Bookmark this section for easy access.

esptool.py chip_id - Get Chip Info & Flash Details

Before flashing, it's useful to check what ESP32 chip you're working with and verify flash memory details.

Get chip information:

esptool.py --port <your-port> chip_id

Returns details about your ESP32, including its unique chip ID.

Check flash memory size:

esptool.py --port <your-port> flash_id

Reads the flash chip's manufacturer, size, and speed.

esptool.py read_flash - Backup & Dump ESP32 Firmware

Pro Tip: Always back up your ESP32 firmware before making major changes!

Backup / dump entire flash memory (read_flash):

esptool.py --port <your-port> read_flash 0x00000 0x400000 backup.bin

Adjust 0x400000 based on your ESP32's flash size (4MB shown here)

Saves the full flash content into backup.bin, allowing you to restore later if needed. Also useful to dump firmware from an existing device before reflashing.

Restore firmware from backup:

esptool.py --port <your-port> write_flash 0x00000 backup.bin

Writes the backup back onto the ESP32, restoring it to its previous state.

esptool.py erase_flash - Erase & Re-flash

Erase the entire flash memory:

Recommended before flashing new firmware to prevent conflicts

esptool.py --port <your-port> erase_flash

Flash new firmware:

esptool.py --chip esp32 --port <your-port> --baud 460800 write_flash -z 0x1000 firmware.bin

Flag explanations:

--chip esp32 → Specifies the ESP32 chip

--port <your-port> → Your serial port (e.g., COM3, /dev/ttyUSB0)

--baud 460800 → Speeds up flashing (reduce if errors occur)

-z 0x1000 → Writes firmware starting at the correct memory offset

For more details, check out using ESP32 with Arduino IDE

Baud Rates - Speed Up Flashing

If flashing takes too long, increase the baud rate for faster uploads:

esptool.py --port <your-port> --baud 921600 write_flash -z 0x1000 firmware.bin

Note: Higher baud rates can cause unstable flashing. If you encounter errors, lower it to 460800 or 115200

Tip: Most ESP32 boards work reliably at 460800, which offers a good balance between speed and stability.

Related Guides #

Wrapping Up #

With esptool.py, you now have full control over flashing, backing up, and managing your ESP32 firmware. Whether you're installing ESPHome, setting up MicroPython, or recovering from a failed flash, these commands will get you there.

Quick troubleshooting checklist:

• ✓ Double-check your USB drivers are installed correctly (CP210x or CH340)
• ✓ Verify the correct serial port is selected
• ✓ Try lowering the baud rate to 460800 or 115200 if flashing fails
• ✓ Hold the BOOT button during connection if the chip doesn't respond

Need help with connection issues? See our detailed guide on ESP32 USB-to-UART Bridges.