Flash ESP32 Firmware Like a Pro using esptool.py - Guide
Learn how to flash, erase, and backup ESP32 firmware using `esptool.py`. This step-by-step guide covers installation, first-time flashing, and essential commands.
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 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.
✨ When to Use esptool.py:
💡 Pro Tip: 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.
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.
1 Install Python 3
Before using esptool.py, you need Python 3 installed on your system.
macOS
Using Homebrew:
brew install pythonLinux
Using apt (Ubuntu/Debian):
sudo apt install python3 python3-pip2 Verify Python Installation
Once installed, confirm Python is working by checking the version:
python3 --version✅ If you see 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 esptoolCheck 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
Use a USB cable to connect your ESP32 development board to your computer.
⚠️ Important: 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
Command Prompt:
wmic path Win32_SerialPort get DeviceID,NameOr 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
📖 For more details, check out this guide on USB-to-UART bridges.
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💡 Replace <your-port> with your serial port (e.g., /dev/ttyUSB0 or COM3)
Expected output:
Connecting...
Chip erase completed successfully in 2.5s⚙️ Tip: You may need to hold down the BOOT/FLASH button on your ESP32 to establish a connection. Once erasing starts, you can release it.
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?
🔥 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 → 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 – Essential Commands #
Quick reference for the most common esptool.py commands. Bookmark this section for easy access! 🔖
🔍 Get ESP32 Chip and Flash Information
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_idReturns details about your ESP32, including its unique chip ID.
💾 Check flash memory size:
esptool.py --port <your-port> flash_idReads the flash chip's manufacturer, size, and speed.
💾 Backup and Restore ESP32 Firmware
⚠️ Pro Tip: Always back up your ESP32 firmware before making major changes!
📤 Backup entire flash memory:
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.
📥 Restore firmware from backup:
esptool.py --port <your-port> write_flash 0x00000 backup.binWrites the backup back onto the ESP32, restoring it to its previous state.
🧹 Erase and Flash Firmware
🗑️ Erase the entire flash memory:
esptool.py --port <your-port> erase_flash
⚡ Flash new firmware:
esptool.py --chip esp32 --port <your-port> --baud 460800 write_flash -z 0x1000 firmware.binFlag 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
🚀 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 #
Explore these helpful resources to get the most out of your ESP32 development:
ESP32 USB-to-UART Bridges
Fix serial port connection issues and install drivers
ESPHome First-Time Setup
Complete guide for flashing ESPHome firmware
MicroPython on ESP32
Get started with Python programming on ESP32
Arduino IDE for ESP32
Complete setup guide for Arduino development
Official esptool.py Documentation
Comprehensive technical reference from Espressif
Wrapping Up #
You're Ready to Flash!
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 troubleshooting a failed flash, these commands will help you get the job done efficiently.
⚡ Quick Troubleshooting Checklist:
- ✓ Double-check your USB drivers are installed correctly
- ✓ Verify the correct serial port is selected
- ✓ Try adjusting the baud rate if flashing fails
- ✓ Hold the BOOT button if connection issues persist
💡 Need help with connection issues? Check out our comprehensive guide on ESP32 USB-to-UART Bridges for in-depth troubleshooting.
Now go ahead and flash your ESP32 with confidence!