Flash ESP32 Firmware Like a Pro using esptool.py - Guide

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.

esptool.py is a command-line tool designed for ESP32 and ESP8266 chips, primarily used for flashing firmware, debugging, and performing low-level hardware operations. It is developed by Espressif and is widely used across different development environments.

While most development platforms provide a graphical or automated way to flash firmware, the esptool.py is useful when:

• You need manual control over flashing parameters.
• You want to backup or restore flash memory.
• Troubleshooting connection issues or erasing flash memory.
• Or simply for a quick ESP32 flash with minimal setup.

Since many ESP32 development boards come with different USB-to-UART bridge chips (learn more here), esptool.py allows setting the correct baud rate and connection settings when default options fail.

In this guide, we'll go through essential esptool.py commands in a cheat sheet format to make flashing ESP32 firmware fast and easy! 🚀

Setting Up esptool.py #

Before you can start using esptool.py to flash firmware, back up binaries, or manage your ESP32, you’ll need to get it installed and ready to go on your computer. The process is straightforward and works across platforms like macOS, Windows, and Linux. Here’s how to set it up step by step.

1. 🛠️ Install Python #

Before using esptool.py, you need Python 3 installed on your system.

• 🖥️ Windows: Download and install Python from the official Python website. During installation, check the box to add Python to your system PATH.

• 🍏 macOS: Python is often pre-installed, but it’s best to update to the latest version. If you have Homebrew, just run:

brew install python

• 🐧 Linux: Most distributions include Python by default. If not, install it using your package manager:

sudo apt install python3 python3-pip

2. ✅ Verify Python Installation #

Once installed, confirm Python is working by checking the version:

python3 --version

If you see an output like Python 3.x.x, you're good to go! 🎉

3. 📥 Install esptool.py #

Now that Python is set up, let's install esptool.py and get flashing! 🚀

pip install esptool

Check that it's installed correctly:

esptool.py version

If you see output like esptool.py v4.x.x, it's ready to use!

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

Now that you’ve installed esptool.py and set up your environment, it’s time to flash your ESP32! If you’re installing new firmware, updating an existing one, or troubleshooting, esptool.py gives you full control over the process.

🔌 1. Connect Your ESP32 to Your Computer #

Use a USB cable to connect your ESP32 development board to your computer. ⚠️ Ensure the cable supports data transfer, as some are power-only!

🔍 2. Identify the Serial Port #

To communicate with your ESP32, find out which serial port it's connected to:

• 🖥️ Windows:

  • Open Command Prompt and run:

    wmic path Win32_SerialPort get DeviceID,Name

  • Look for a device labeled as USB-to-UART, Silicon Labs CP210x, or CH340.
  • Alternatively, open Device Manager (Win + X → Device Manager) and check under Ports (COM & LPT). Your ESP32 should appear as "USB Serial Device (COMx)" or similar.

• 🍏 macOS:

  • Open Terminal and execute:

    ls /dev/tty.*

  • Identify the port associated with your ESP32, typically named /dev/tty.usbmodemXXXX.
  • 

• 🐧 Linux:

  • Run in Terminal:

    ls /dev/ttyUSB*

  • Your ESP32 should appear as /dev/ttyUSB0 or similar.

❌ ESP32 not detected? You might need to install USB-to-Serial drivers:

• 🛠️ CP210x (Silicon Labs): Download here
• 🛠️ CH340 (WCH): Download here

For more details on ESP32's USB-to-UART bridges, check out this guide.

🧹 3. Erase Flash Memory (Optional but Recommended) #

Before flashing new firmware, it's good practice to erase the existing flash memory to prevent conflicts:

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

Replacewith the correct serial port, e.g., /dev/ttyUSB0. You may need to hold down the BOOT/FLASH button on your ESP32 to establish a connection. Once erasing starts, you can release the button.

Expected output:

Connecting...
Chip erase completed successfully in 2.5s

4. 🔥 Flash the Firmware #

Now, it's time to upload your new firmware! Ensure you have the firmware binary file (e.g., firmware.bin) ready.

📥 Where to Get ESP32 Firmware?

The firmware you need depends on your project. Here are some common sources:

• WLED – If you're setting up an ESP32 for addressable LED control, you can download the latest WLED firmware from the official site.
• ESPHome – For smart home automation, you can generate a custom ESPHome firmware through Home Assistant or download a precompiled binary.
• MicroPython – If you're running Python on your ESP32, get the latest stable MicroPython firmware from the official site.
• Tasmota – If you’re flashing your ESP32 for MQTT-based home automation, you can find Tasmota firmware builds online.
• Custom Firmware – If you're working on your own project, your firmware might be compiled from the Arduino IDE or PlatformIO.

Make sure to download the correct .bin file for your ESP32 board model! 🔥

Run the following command:

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

📌 Explanation of flags:

• --chip esp32 → Specifies the target chip (ESP32).
• --port <your-port> → The serial port your ESP32 is connected to.
• --baud 460800 → Sets the baud rate for faster flashing (adjust if needed).
• write_flash -z 0x1000 firmware.bin → Writes firmware to flash memory.

Expected output:

Hash of data verified.
Leaving...
Hard resetting via RTS pin...

Congratulations! Your ESP32 is now flashed and ready to go! ✅

📌 esptool.py Cheat Sheet – Most Used Commands 🔥 #

Here’s a quick reference for essential esptool.py commands, whether you're flashing firmware, debugging, or backing up your ESP32. Keep this handy for your next project!

🔍 Get ESP32 Chip and Flash Information #

Before flashing, it’s useful to check what ESP32 chip you're working with:

• Get chip info:

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

This command returns details about your ESP32, including its unique chip ID.

• Check flash memory size:

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

This reads the flash chip’s manufacturer, size, and speed.

💾 Backup and Restore ESP32 Firmware #

It's always a good idea to back up your ESP32 firmware before making major changes.

• Backup entire flash memory (adjust size 0x400000 if needed):

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

This saves the full flash content into backup.bin, allowing you to restore later if needed.

• Restore firmware from backup:

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

This writes the backup back onto the ESP32.

🧹 Erase and Flash Firmware #

• Erase the entire flash memory (recommended before flashing new firmware):

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

• Flash new firmware (replace firmware.bin with your actual file):

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

• --chip esp32 → Specifies the ESP32 chip.
• --port <your-port> → The serial port your ESP32 is connected to.
• --baud 460800 → Speeds up flashing (reduce if errors occur).
• -z 0x1000 → Writes firmware starting at the correct memory offset.

For more on flashing ESP32 firmware, check out our guide on using ESP32 with Arduino IDE.

🚀 Speed Up Flashing #

If flashing takes too long, try increasing the baud rate:

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

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

🔗 Related Guides #

• ESP32 USB-to-UART Bridges – Fix serial port connection issues.
• ESPHome First-Time Setup – If you're flashing ESPHome firmware.
• MicroPython on ESP32 – Guide to installing MicroPython.
• Arduino IDE for ESP32 - Guide to installing Arduino IDE.
• Official esptool.py Documentation

Now you're all set to flash your ESP32 like a pro! 🚀🔥

🎯 Wrapping Up #

With esptool.py, you have full control over flashing, backing up, and managing your ESP32 firmware. Whether you're installing ESPHome, setting up MicroPython, or troubleshooting a failed flash, these commands will help you get the job done efficiently.

If you run into issues, double-check your USB drivers, serial port, and baud rate settings. For more in-depth troubleshooting, see our guide on ESP32 USB-to-UART Bridges.

Now go ahead and flash your ESP32 with confidence! 🚀🔥