Flashing MicroPython Firmware with esptool.py on ESP32 and ESP8266

This post shows how to flash MicroPython firmware on ESP32/ESP8266 boards using the esptool.py. It works on Windows, Mac OS X, and Linux. For the official documentation, you can visit the esptool.py GitHub page.

Tip: for an easier method to flash the ESP32/ESP8266 with MicroPython, we recommend reading this guide to flash MicroPython with uPyCraft IDE. However, we’ve recently received comments from our readers about having trouble installing/using uPyCraft IDE. For that reason, we’re posting an alternative method using the esptool.py software.

Installing esptool.py in your computer

To work with esptool.py, you’ll need either Python 2.7, Python 3.4 or a newer Python installation on your system. We recommend using Python 3.7.X, so go to Python’s website and install it on your computer.

With Python 3 installed, open a Terminal window and install the latest stable esptool.py release with pip:

pip install esptool

Note: with some Python installations that command may not work and you’ll receive an error. If that’s the case, try to install esptool.py with:

  • pip3 install esptool
  • python -m pip install esptool
  • pip2 install esptool

Setuptools is also a requirement that is not available on all systems by default. You can install it with the following command:

pip install setuptools

After installing, you will have esptool.py installed into the default Python executables directory and you should be able to run it with the command esptool.py. In your Terminal window, run the following command:

python -m esptool

If it was installed properly, it should display a similar message (regardless of your operating system):

With esptool.py installed on your computer, you can easily flash your ESP32 or ESP8266 boards with the MicroPython firmware. This post is divided into two parts, read Part 1 or Part 2 depending on your board:

  • Part 1 – ESP32
  • Part 2 – ESP8266

Note: after installing MicroPython firmware on your ESP32 or ESP8266, you can go back and use Arduino IDE again. You just need to upload code using Arduino IDE. Then, if you want to use MicroPython again, you need to flash MicroPython firmware.

[Part 1 – ESP32] Downloading and Flashing the MicroPython Firmware on ESP32

To download the latest version of MicroPython firmware for the ESP32, go to the MicroPython Downloads page and scroll all the way down to the ESP32 section.

You should see a similar web page (see figure below) with links to download .bin files. Download the latest release. At the time of writing this article, the latest release is v1.17 (2021-02-02).bin. Don’t download the Nighlty builds; those versions are not stable and are only recommended for advanced programmers.

Download MicroPython Firmware

Note: if you’re using a different board (like a PyBoard, WiPy, or other), go to MicroPython Downloads page and download the right firmware for your board.

Finding the Serial Port Name

It’s a bit different to find the Serial port name in each operating system, so for simplicity reasons we recommend finding your ESP serial port name through the Arduino IDE. Follow these steps:

  1. Connect your board to your computer
  2. Open the Arduino IDE
  3. Go to Tools > Port
  4. Save your ESP32 serial port name (in our case it’s COM7)
  5. Close your Arduino IDE software

Important: if you plug your ESP32 board into your computer, but you can’t find the ESP32 Port available in your Arduino IDE, it might be one of these two problems: 1. USB drivers missing or 2. USB cable without data wires.

1. If you don’t see your ESP’s COM port available, this often means you don’t have the USB drivers installed. Take a closer look at the chip next to the voltage regulator on board and check its name.

The ESP32 DEVKIT V1 DOIT board uses the CP2102 chip.

Go to Google and search for your specific chip to find the drivers and install them in your operating system.

You can download the CP2102 drivers on the Silicon Labs website.

After they are installed, restart the Arduino IDE and you should see the serial port in the Tools > Port menu.

2. If you have the drivers installed, but you can’t see your device, double-check that you’re using a USB cable with data wires.

USB cables from powerbanks often don’t have data wires (they are charge only). So, your computer will never establish a serial communication with your ESP32. Using a proper USB cable should solve your problem.

Finding your MicroPython .bin file

After downloading the ESP32 .bin file, it should be in your Downloads folder. So, with your Terminal window, you’ll need to navigate to the Downloads folder using the cd command:

cd Downloads

List all files in your Downloads folder to ensure that’s where the .bin file is located. In Windows, you use:

dir

On Mac OS X or Linux, run the next command:

ls

As you can see in the preceding screenshot, the ESP32 .bin file is located in the Downloads folder: esp32-20190113-v1.9.4-779-g5064df207.bin.

Erasing ESP32 Flash Memory

Before flashing the MicroPython firmware, you need to erase the ESP32 flash memory. So, with your ESP32 connected to your computer, hold-down the “BOOT/FLASH” button in your ESP32 board:

Note: if your board doesn’t have a BOOT/FLASH button, it will probably go into flashing mode automatically.

While holding down the “BOOT/FLASH” button, run the following command to erase the ESP32 flash memory:

python -m esptool --chip esp32 erase_flash

When the “Erasing” process begins, you can release the “BOOT/FLASH” button. After a few seconds, the ESP32 flash memory will be erased.

Note: if after the “Connecting …” message you keep seeing new dots appearing, it means that your ESP32 is not in flashing mode. You need to repeat all the steps described earlier and hold the “BOOT/FLASH” button again to ensure that your ESP32 goes into flashing mode and completes the erasing process successfully.

Flashing MicroPython Firmware on ESP32 with esptool.py

With your ESP32 flash memory erased, you can finally flash the MicroPython firmware. You need your serial port name (COM7 in our case) and the ESP32 .bin file location. Replace the next command with your details:

python -m esptool --chip esp32 --port <serial_port> write_flash -z 0x1000 <esp32-X.bin>

In our case, the command looks like this:

python -m esptool --chip esp32 --port COM7 write_flash -z 0x1000 esp32-20190113-v1.9.4-779-g5064df207.bin

Hold down the “BOOT/FLASH“, before running the flash command. After a few seconds this is what you should see:

Your ESP32 was successfully flashed with MicroPython firmware!

Note: if you receive an error trying to flash the firmware, run the command again and make sure you are holding down the ESP32 “BOOT/FLASH” button.

[Part 2 – ESP8266] Downloading and Flashing the MicroPython Firmware on ESP8266

To download the latest version of MicroPython firmware for the ESP32, go to the MicroPython Downloads page and scroll all the way down to the ESP8266 section.

You should see a similar web page (see figure below) with links to download .bin files. Download the latest release. At the time of writing this article, the latest release is v1.17 (2021-02-02).bin. Don’t download the Nighlty builds; those versions are not stable and are only recommended for advanced programmers.

Download MicroPython Firmware

Note: if you’re using a different board (like a PyBoard, WiPy, or other), go to MicroPython Downloads page and download the right firmware for your board.

Finding the Serial Port Name

It’s a bit different to find the Serial port name in each operating system, so for simplicity reasons we recommend finding your ESP serial port name through the Arduino IDE. Follow these steps:

  1. Connect your board to your computer
  2. Open the Arduino IDE
  3. Go to Tools > Port
  4. Save your ESP8266 serial port name (in our case it’s COM4)
  5. Close your Arduino IDE software

Important: if you plug your ESP8266 board to your computer, but you can’t find the ESP8266 Port available in your Arduino, it might be one of these two problems: 1. USB drivers missing or 2. USB cable without data wires.

1. If you don’t see your ESP’s COM port available, this often means you don’t have the USB drivers installed. Take a closer look at the chip next to the voltage regulator on board and check its name.

The ESP8266 ESP-12E NodeMCU board uses the CP2102 chip.

Go to Google and search for your specific chip to find the drivers and install them in your operating system.

You can download the CP2102 drivers on the Silicon Labs website.

After they are installed, restart the Arduino IDE and you should see the serial port in the Tools > Port menu.

2. If you have the drivers installed, but you can’t see your device, double-check that you’re using a USB cable with data wires.

USB cables from powerbanks often don’t have data wires (they are charge only). So, your computer will never establish a serial communication with your ESP8266. Using a proper USB cable should solve your problem.

Finding your MicroPython .bin file

After downloading the ESP8266 .bin file, it should be in your Downloads folder. So, with your Terminal window, you’ll need to navigate to the Downloads folder using the cd command:

cd Downloads

List all files in your Downloads folder to ensure that’s where the .bin file is located. In Windows, you use:

dir

On Mac OS X or Linux, run the next command:

ls

As you can see in the preceding screenshot, the ESP8266 .bin file is located in the Downloads folder: esp8266-20180511-v1.9.4.bin.

Erasing ESP8266 Flash Memory

Before flashing the MicroPython firmware, you need to erase the ESP8266 flash memory. So, with your ESP8266 connected to your computer, hold-down the “BOOT/FLASH” button in your ESP8266 board:

While holding down the “BOOT/FLASH” button, run the following command to erase the ESP8266 flash memory:

python -m esptool --chip esp8266 erase_flash

When the “Erasing” process begins, you can release the “BOOT/FLASH” button. After a few seconds, the ESP8266 flash memory will be erased.

Note: if after the “Connecting …” message you keep seeing new dots appearing, it means that your ESP8266 is not in flashing mode. You need to repeat all the steps described earlier and hold the “BOOT/FLASH” button again to ensure that your ESP8266 goes into flashing mode and completes the erasing process successfully.

Flashing MicroPython Firmware on ESP8266 with esptool.py

With your ESP8266 flash memory erased, you can finally flash the MicroPython firmware. You need your serial port name (COM7 in our case) and the ESP8266 .bin file location. Replace the next command with your details:

python -m esptool --chip esp8266 --port <serial_port> write_flash --flash_mode dio --flash_size detect 0x0 <esp8266-X.bin>

In our case, the final command looks like this:

python -m esptool --chip esp8266 --port COM4 write_flash --flash_mode dio --flash_size detect 0x0 esp8266-20180511-v1.9.4.bin

Hold down the “BOOT/FLASH“, before running the flash command. After a few seconds this is what you should see:

Your ESP8266 was successfully flashed with MicroPython firmware!

Note: if you receive an error trying to flash the firmware, run the command again and make sure you are holding down the ESP8266 “BOOT/FLASH” button.

Troubleshooting

If you encounter a permission error while trying to run the esptool command, open the command prompt as a administrator (or as sudo on Linux).

run commands as an administrator command prompt

Wrapping Up

We hope you’ve found this tutorial useful. Your ESP32/ESP8266 should now be flashed with MicroPython firmware. To learn more about MicroPython read: Getting Started with MicroPython on ESP32 and ESP8266.

If you liked this post, you might like our next ones, so make sure you subscribe to the RNT blog and download our free electronics eBooks.



Learn how to build a home automation system and we’ll cover the following main subjects: Node-RED, Node-RED Dashboard, Raspberry Pi, ESP32, ESP8266, MQTT, and InfluxDB database DOWNLOAD »
Learn how to build a home automation system and we’ll cover the following main subjects: Node-RED, Node-RED Dashboard, Raspberry Pi, ESP32, ESP8266, MQTT, and InfluxDB database DOWNLOAD »

Enjoyed this project? Stay updated by subscribing our newsletter!

19 thoughts on “Flashing MicroPython Firmware with esptool.py on ESP32 and ESP8266”

  1. Worked perfectly while using Thonny 3.1.2 on Ubuntu; watch out for the micro USB cable without the data wires!! (luckily I have like 10 cables)

    A way to check if your issue is with your cable is before you plug in the ESP, type in terminal lsusb and then plug in your ESP and type lsusb again and compare the two. If nothing changes try another cable.

    Reply
  2. Great ! I tried once and work perfectly 🙂
    For me as beginner I suggest to add commands “pip install rshell” then “rshell -p COMx repl” once flashing completed, so beginner can test the micropython firmware on their board.

    Thanks 🙂

    Reply
  3. Hi,

    When trying to flash ESP32, get the following result:

    ‘could not open port 17 FileNotFound Error (2, The system cannot find the file specified, None, 2)’

    Have checked & port 17 is the correct port.

    Reply
  4. Hello and thank you.
    This is the tutorial that works on the first connection.
    Only info to USB cables, I will confirm what has already been mentioned and all USB cables need to be sorted and marked, or for example divided into plastic bags, together only charging and together data and some older ones can also be thrown away in separate collection.

    Reply
  5. The firmware download page for the ESP32, https://micropython.org/download/esp32/ offers multiple versions of the firmware. The most current version at this time, esp32-20210418-v1.15.bin, is missing some standard modules, including urequests. You can install the urequests module (from PyPI) in the /lib folder of your ESP32 using “Manage packages…” under the “Tools” tab of Thonny. You will be offered multiple choices. I’m currently testing micropython-urequests, version 0.9.1 from Paul Sokolovsky.

    Furthermore, in some situations, such as using the _thread module for multithreading, you can expect problems that differ depending on the firmware that you are using on the ESP32. In my situation, using firmware: esp32-idf4-20210202-v1.14.bin or esp32-idf3-20210202-v1.14.bin results in corruption of the WiFi DNS settings and OSErrors in the urequest modules packaged in those firmware versions. Others see this on other boards: https://github.com/micropython/micropython/issues/6492

    Reply
  6. erase successfully:

    C:\Users\Imam\AppData\Local\Programs\Python\Python310>python -m esptool –chip esp32 erase_flash
    esptool.py v3.2
    Found 1 serial ports
    Serial port COM3
    Connecting….
    Chip is ESP32-D0WDQ6 (revision 1)
    Features: WiFi, BT, Dual Core, 240MHz, VRef calibration in efuse, Coding Scheme None
    Crystal is 40MHz
    MAC: 7c:9e:bd:60:74:0c
    Uploading stub…
    Running stub…
    Stub running…
    Erasing flash (this may take a while)…
    Chip erase completed successfully in 0.0s

    Hard resetting via RTS pin…

    But not writing, getting following error:

    C:\Users\Imam\AppData\Local\Programs\Python\Python310>python -m esptool –chip esp32 –port COM3 write_flash -z 0x1000 C:\Users\Imam\Downloads\esp32-20220117-v1.18.bin
    esptool.py v3.2
    Serial port COM3
    Connecting….
    Chip is ESP32-D0WDQ6 (revision 1)
    Features: WiFi, BT, Dual Core, 240MHz, VRef calibration in efuse, Coding Scheme None
    Crystal is 40MHz
    MAC: 7c:9e:bd:60:74:0c
    Uploading stub…
    Running stub…
    Stub running…
    Configuring flash size…
    Flash will be erased from 0x00001000 to 0x0017cfff…
    Compressed 1555136 bytes to 1022998…
    Wrote 1555136 bytes (1022998 compressed) at 0x00001000 in 91.6 seconds (effective 135.9 kbit/s)…
    File md5: 25df6c76dee00975166ace794dda7b08
    Flash md5: f4635f8f6400bd682f736dec480f8512
    MD5 of 0xFF is 57068f8d6bd561d3021e7da5f12a5032

    A fatal error occurred: MD5 of file does not match data in flash!

    Reply
  7. For mac users in 2022, I came upon these problems:
    1. I had a USB-C to USB converter between the computer and the board. With this setup Arduino couldn’t find the board.
    I ended up buying a USB-C to USB-micro cord that solved the problem

    I installed esptool on the wrong version of python

    esp32 % python -m esptool
    /System/Library/Frameworks/Python.framework/Versions/2.7/Resources/Python.app/Contents/MacOS/Python: No module named esptool
    solved it with specifying the python number:
    esp32 % python3.9 -m esptool

    running python3.9 -m esptool –-chip esp32 erase_flash gave this error
    esptool: error: argument operation: invalid choice: ‘–-chip’
    I’m not sure how to send in arguments the correct way, but workaround is to remove it completely. ESPtool was able to identify the chip itself

    python3.9 -m esptool erase_flash

    esptool.py v3.2
    Found 4 serial ports
    Serial port /dev/cu.usbserial-0001
    Connecting….
    Detecting chip type… Unsupported detection protocol, switching and trying again…
    Connecting….
    Detecting chip type… ESP32

    the section about finding the COM port looked different for me.
    I can see /dev/cu.usbserial-0001 and also /dev/cu.SLAB_USBtoUART after installing the cp2102 driver

    I ended up removing the -port argument completely and it ran successfully

    python3.9 -m esptool write_flash -z 0x1000 esp32-20220117-v1.18.bin
    esptool.py v3.2
    Found 4 serial ports
    Serial port /dev/cu.usbserial-0001
    Connecting….
    Detecting chip type… Unsupported detection protocol, switching and trying again…
    Connecting…..
    Detecting chip type… ESP32
    Chip is ESP32-D0WDQ6 (revision 1)
    Features: WiFi, BT, Dual Core, 240MHz, VRef calibration in efuse, Coding Scheme None
    Crystal is 40MHz
    MAC: 94:b9:7e:e5:00:c0
    Uploading stub…
    Running stub…
    Stub running…
    Configuring flash size…
    Flash will be erased from 0x00001000 to 0x0017cfff…
    Compressed 1555136 bytes to 1022998…
    Wrote 1555136 bytes (1022998 compressed) at 0x00001000 in 90.6 seconds (effective 137.4 kbit/s)…
    Hash of data verified.

    Leaving…
    Hard resetting via RTS pin…

    Reply
  8. Thank you very much for all your tutorials, those are incredible!

    After I flash my board with MicroPyhton firmware, will it be possible to continue programming with Arduino IDE and c++ as before the flash, or I will need to flash back to “original firmware”?

    Reply
    • Hi.
      After flashing micropython, if you want to get back using Arduino IDE, you just need to upload a new code using Arduino IDE.
      It’s as simple as that.
      Regards,
      Sara

      Reply
  9. OK . Latest OS version on Raspberry Pi is Bookworm. Issuing the command
    pip install esptool will result in error: externally-managed-environment.
    There are various options to solve that and I elected to use
    pipx install esptool
    then make in available though the system path by
    That all seems to work except instead of issuing the command esptool it seems to be necessary to issue command exptool.py. So the commands to erase the flash memory and install micropython on an 8266 for me were
    esptool.py -p /dev/ttyUSB0 –chip esp8266 erase_flash
    and
    esptool.py -p /dev/ttyUSB0 –chip esp8266 write_flash –flash_mode dio –flash_size detect 0x0 ESP8266_GENERIC-20231005-v1.21.0.bin
    where /dev/ttyUSB0 is the port and ESP8266_GENERIC-20231005-v1.21.0.bin the dowloaded firmware.
    Hope that helps anyone who is trying to sort that out on a RPi or possibly on any other updated OS such as Ubuntu 23.10

    Reply
  10. Hello. Last night I reinstalled Thonny to the latest version 4.1.4. I downloaded the latest stable OTA firmware for both ESP32 and 8266 from the Espressif site and started uploading to the 8266 board. After finishing programming, Shell -ThonnyIDE- began typing out various characters at high speed and flashing LEDs at high frequency, and Thonny “hardened”. I had to open a new window – in the terminal with esptool.py erase everything. This happened with both ESP32 and 8266. I work in Debian 12, Python is 3.12, but both Debian and Python were with the previous version of Thonny. I’m not an IT, just a playing retiree who used to work with electronics. Thank you for your advice.

    Reply

Leave a Comment

Download Our Free eBooks and Resources

Get instant access to our FREE eBooks, Resources, and Exclusive Electronics Projects by entering your email address below.