How to install MicroPython on ESP32

Hello MicroPython enthusiasts! After making so many MicroPython tutorials, I realized that I never wrote a guide on how to install the damn thing in the first place 🤦‍♂️ That's what this guide is for.

I've found 2 ways to install it on an ESP32 - one is using the GUI in the Thonny editor, and the other way is using a command line tool called esptool. The Thonny method works for other microcontrollers as well, whereas the esptool method only works for the ESP-series microcontrollers, which include the ESP32 and the older ESP8266.

The Thonny method is easier, especially for beginners, whereas the command line method makes you look like an l33t haxx0r elite hacker so you can impress your friends 😎 Jokes aside, I will discuss the actual pros and cons of each method at the end of each section below.

First off, let's learn how to install MicroPython using Thonny!

Option A: Install MicroPython using Thonny

1. Connect your microcontroller to your computer via USB.
2. In Thonny, go to Menu -> Tools -> Options

3. Under the Interpreter tab, select the ESP32 or whichever microcontroller you have.

4. Then at the bottom right of the same window, you'll see what looks like a hyperlink (but it's not) for installing MicroPython. Click on it.

5. In the window that opens, you need to select a few options:
   1. Select your connected microcontroller under "Target port".
   2. Under "MicroPython family", choose the correct chip family for the one you are trying to flash. In my case this was just "ESP32" as I have a generic ESP32-WROOM board which I bought here. But it may be different for you, for e.g. ESP32-C3, ESP32-S3, etc. Check the manual for your board to be sure.
   3. Under "Variant", choose the device variant you are flashing. In my case, this is "ESP / WROOM" but it may be different for your device. Again, check the manual for your board to be sure.
   4. Finally, under "Version", choose which version of MicroPython you want to install. I often just install the latest one, which at the time of this writing is version 1.24.

6. Finally, the moment you've all been waiting for...click dat "Install" button! And watch the glorious progress bar while Thonny wipes your microcontroller clean and infuses it with the magic of MicroPython 😃
7. After the progress bar says "Done", close the Options windows. To confirm that you have correctly installed MicroPython, open the Shell in Thonny and it should show a log from your microcontroller's MicroPython interpreter that says which version it's running.

Pros and cons of installing MicroPython via Thonny

Pros:

• Easy to learn - no need for special CLI tools.
• One method that works for all microcontrollers - no need to learn different methods for each device.

Cons:

• Only the latest 2 versions of MicroPython are available in the options - can't install an older version if needed.
• Hard to automate flashing multiple microcontrollers this way (though I doubt this would affect most people).

Option B: Install MicroPython using esptool

1. Install esptool. The official instructions say to install it using pip, but that would make changes to your global python environment. I highly recommend installing it in an isolated environment instead, for which the easiest method I've found is using pipx (somewhat analogous to "npx" for those who are familiar with nodejs). Here's how to do so:
   1. Install pipx using the instructions in the docs.
      1. On macOS, you may need to first install homebrew if you don't already have it.
      2. On Windows, you will need to first install Scoop.
   2. Run the command pipx install esptool to install esptool.
2. Go to the official page for downloading MicroPython images for ESP32.
3. Select the board you have from the grid of options. In my case, this is the generic "ESP32 / WROOM" by Espressif.
   1. Note: If you can't find your exact board/device or you're flashing a custom board, your best bet is to select the option corresponding to the chip on your board. For e.g. if your device has an ESP32-S3 chip in it, then select "ESP32-S3".
4. Download the firmware .bin image for the version of MicroPython you want. I usually choose the latest one, which at the time of this writing is version 1.24.
   1. Note: if your device has external SPIRAM connected to the ESP32 chip, scroll down to the "Firmware (Support for SPIRAM / WROVER)" section and download an image from there instead, so you can take full advantage of your device's extra RAM :)

5. Connect your microcontroller to your computer via USB.
6. In a terminal, cd into the folder where you downloaded the firmware .bin image.
7. Flash the image onto your device using the commands from the webpage where you downloaded the image. In my experience, you don't need to mention the exact device port as long as you only have one device connected. For e.g. to flash a generic ESP32 board to MicroPython 1.24.1, the commands would be:

esptool.py --chip esp32 erase_flash

esptool.py --chip esp32 --baud 460800 write_flash -z 0x1000 ESP32_GENERIC-20241129-v1.24.1.bin

As you can see, I omitted the --port flag from the above commands and it installed just fine. Again, it is very important to restate that this only works if you have just one device connected to your computer. Please, for the love of programming, don't accidentally wipe or flash any other device that you had connected to your computer! (Although maybe it would be cool if your external mouse was now running MicroPython 🤔 Just a thought).

8. To confirm that you've installed it correctly, you can either:
   1. Run the CLI tool mpremote to check that the device logs the correct version of MicroPython in the REPL.
      1. Note: to install mpremote, run the command pipx install mpremote
   2. Or, you can simply open Thonny and check the Shell to see that the correct version is installed.

Pros and cons of installing MicroPython via CLI

Pros:

• Can install any version of MicroPython on your device - even a really old version, if needed.
• Can be scripted to flash several microcontrollers, if you're building a device flashing station or test station (for your evil plan to take over the world with microcontrollers).

Cons:

• Can only flash Espressif microcontrollers, i.e. ESP8266 and ESP32, with esptool. To flash other chips, you'll need to learn different tools/methods.
• A bit harder to learn than using a GUI. However, as a programmer, I highly recommend learning CLI tools to improve our understanding of what GUIs do under the hood 🔧

In conclusion

If you found this valuable, I do post MicroPython tutorials once every ~2-4 weeks so do hit Follow/Subscribe below if you'd like me to email you when my next tutorial is out! I don't spam you so don't worry - it's just MicroPython tutorials. If you'd like to ask questions, give feedback or just chat then hit me up on twitter/X.

That's it! Hope you learned something new today (I certainly didn't know about the Thonny method when I started out). See you next time on Sssecrets of MicroPython 🐍!