Install MicroPython on ESP32 with Thonny or esptool

MicroPython lets you program an ESP32 with a compact implementation of Python. You can edit a script, run it interactively, read sensors, control GPIO pins, and build networked projects without compiling a traditional Arduino sketch for every change. The first installation has two distinct jobs: put the correct MicroPython firmware on the board, then connect an editor to the board's serial REPL.

This guide walks through both common workflows: Thonny's graphical installer and the command-line esptool utility. It also explains how to identify your ESP32 variant, choose a firmware build, erase an old installation when necessary, save a script as main.py, and diagnose common USB and serial problems.

Important: ESP32 boards vary. An original ESP32, ESP32-S2, ESP32-S3, ESP32-C3, and ESP32-C6 are not interchangeable firmware targets. Confirm the chip marking or board documentation before flashing. Firmware for the wrong chip may fail to boot or may not be detected correctly.

1. What you need before starting

Prepare an ESP32 development board, a known-good USB data cable, a computer, and a stable USB port. A cable that only carries power can light the board's LED while providing no serial connection, so test with a data-capable cable if no port appears.

Install a current version of Thonny from its official website, or install Python and the Espressif-maintained esptool package if you prefer a terminal workflow. Download MicroPython firmware only from the official MicroPython download page for your exact chip family. Avoid random firmware files from file-sharing sites: a binary can be corrupted, built for another chip, or modified.

Before flashing, close Arduino IDE Serial Monitor, PuTTY, VS Code serial extensions, and any other application that may own the COM port or serial device. Do not connect external circuitry while troubleshooting the initial installation. Start with the board alone so that wiring faults and peripheral power requirements do not complicate the diagnosis.

You may need a USB-to-UART driver depending on the board's interface chip. Common chips include CP210x and CH340 variants, but the board's actual hardware determines which driver is appropriate. Use the chip vendor's official driver and your operating system's normal installation process.

2. Identify your ESP32 chip and board

Read the module shield or chip label and check the board seller's specification. A module labelled ESP32-WROOM-32 is usually an original ESP32-family module; ESP32-S3, ESP32-C3, and other variants should be treated as separate targets. Board names such as “ESP32 DevKit” are not precise enough on their own because multiple chip families can be sold under similar names.

If you already have a working serial console, an existing firmware may report the chip type, but a blank board may not. Check the module label, board documentation, or the USB serial adapter marking. The USB adapter identifies the serial bridge, not necessarily the ESP32 itself.

Choose the MicroPython download that explicitly matches the chip family. Read the download page notes for minimum flash size, special builds, and supported peripherals. If the board has external flash or PSRAM, do not assume every build supports every memory configuration identically. For a first experiment, choose the standard stable build recommended for the target family rather than an experimental nightly build unless you need a specific fix.

Keep the downloaded firmware file in a clearly named folder. Record the filename and source so you can repeat the installation later. Never infer the flashing address solely from a filename: use the instructions accompanying that firmware and the flashing method you select.

3. Install firmware with Thonny

1. Connect the ESP32 directly to the computer with a data-capable USB cable.
2. Open Thonny and select Tools → Options → Interpreter (the exact wording can vary slightly by release).
3. Choose the MicroPython interpreter for ESP32 and select the serial port associated with the board.
4. If Thonny offers an installation or firmware configuration option, open it and select the correct ESP32 family.
5. Select the official firmware file you downloaded, or let Thonny download a suitable stable build if that option is available.
6. Follow the installer prompts. Some boards enter download mode automatically; others require you to hold BOOT while starting the flash operation and release it when the tool begins writing.
7. Wait for the operation to finish. Do not unplug the board or close Thonny while the flash is in progress.
8. Return to the interpreter pane, reconnect if necessary, and press Enter in the Shell.

A successful connection normally displays a MicroPython banner or a prompt such as >>>. If the Shell remains silent, try pressing Enter once, then use Thonny's stop/restart or reconnect control. A silent shell does not by itself prove that flashing failed; the port may not have reopened or another program may still own it.

Thonny's installer interface changes over time, so follow the labels shown in your installed version rather than relying on a particular screenshot. If the installer reports an unsupported chip or cannot identify the target, stop and verify the selected firmware family instead of repeatedly flashing the same file.

4. Install firmware with esptool

The command-line workflow is useful when you want repeatable steps or need to inspect a failure message. Install a recent version in the Python environment you intend to use:

python -m pip install --upgrade esptool
python -m esptool version

On some systems, the command may be python3 rather than python. Current esptool releases may use a slightly different command syntax from older versions, so consult the installed version's help if a command is rejected.

List serial ports using your operating system or a serial-port listing tool, then identify the port that appears when you plug in the board. On Windows it may look like COM5; on macOS it may look like /dev/cu.usbserial-...; Linux commonly exposes a path under /dev/ttyUSB... or /dev/ttyACM....

First check that the chip can be detected. Substitute the actual port:

python -m esptool --port COM5 chip_id

The exact command can vary by esptool version and chip family. If the tool cannot connect, try the board's download-mode procedure: hold BOOT, start the command, and release BOOT when the connection begins. Some boards use different button behaviour, so check the board documentation.

Do not guess the flash offset. A MicroPython firmware image may be intended to be written at a specific address, and the correct procedure depends on the target and image format. Use the official MicroPython installation instructions for your chip and the current esptool syntax. If those instructions tell you to erase first, use the erase command for the detected port, then write the image to the specified address. Erasing removes existing firmware and data, so back up anything important before doing it.

5. First connection and the REPL

The REPL is the interactive Python prompt running on the ESP32. It is useful for quick checks because you can enter a statement and see the result immediately. In Thonny, select the ESP32 MicroPython interpreter and the correct serial port, then press Enter in the Shell.

Try a basic test:

print("Hello from SolderHub")

Then inspect the runtime:

import sys
print(sys.implementation)
print(sys.platform)

On MicroPython, sys.platform commonly identifies the runtime platform, while sys.implementation provides implementation information. Exact output varies with the firmware build.

If the Shell reports a soft reboot after you stop a program, that is normal. If you see unreadable characters, check the baud rate and whether another application is sending data. Boot messages and REPL output can use different baud settings depending on the board and firmware. Thonny normally manages the interactive connection, so avoid changing serial settings without a reason.

To test GPIO, use the board's built-in LED only if its pin is documented. ESP32 development boards do not all place the onboard LED on the same GPIO, and some boards have no user LED. Never copy a GPIO number from an unrelated board diagram and assume it is safe. For a first test, printing text is enough to verify that the interpreter and serial connection are working.

6. Save and run your first script

Once the REPL works, create a file in Thonny:

from time import sleep

count = 0

while True:
    count += 1
    print("SolderHub test:", count)
    sleep(2)

Choose Run to execute the file. When asked where to save it, select the MicroPython device if you want the file stored on the ESP32. Save it as main.py to make it run automatically at startup. Save it under another name, such as test.py, if you want to launch it manually and avoid having it start every time the board resets.

A continuously running loop can make the Shell feel busy. Use Thonny's stop control to interrupt it. If interruption does not work, press the board's reset button and reconnect. Avoid an infinite loop that never yields or sleeps when you are building networked applications, because it can make the device less responsive and consume unnecessary power.

MicroPython stores files in the device's filesystem, commonly using a flash-backed filesystem. Firmware flashing and filesystem erasing are different operations, but some installation workflows erase existing contents. Keep a local copy of every script. For a larger project, use version control or a dated backup folder rather than relying on the board as the only copy.

7. A safe GPIO example

After confirming the exact pinout, you can test a simple LED circuit. Use an external LED with a current-limiting resistor, for example 220–1,000 ohms, and a GPIO documented as available on your board. Connect GPIO through the resistor to the LED anode and connect the cathode to GND, or follow a verified circuit diagram for your specific board. Do not connect an LED directly across a GPIO and ground.

Example for a verified output-capable pin:

from machine import Pin
from time import sleep

led = Pin(2, Pin.OUT)  # Replace only after checking your board's pinout

while True:
    led.value(not led.value())
    sleep(0.5)

GPIO 2 is only an example and is not suitable for every ESP32 board or every startup configuration. Some pins are strapping pins, connected to onboard hardware, input-only, or used by flash/PSRAM. Check the board schematic before wiring.

If the LED does not blink, verify the physical pin label against the module's GPIO number, the LED's polarity, resistor connection, and ground. If the board resets, disconnect the external circuit and retry the print-only test. Never use GPIO to drive a motor, relay coil, lamp, or other high-current load directly. Use a suitable driver stage and a separate, correctly rated supply where required.

8. Common installation problems

No serial port appears. Try a known data cable, another USB port, and direct connection rather than a hub. Inspect Device Manager on Windows or the device list on your operating system. Install the correct USB-to-UART driver only after identifying the adapter chip. If the board's power LED lights but no device appears, suspect the cable, connector, adapter, or driver before changing firmware.

The port is busy. Close every serial terminal, IDE monitor, and background extension that may hold the port. Disconnect and reconnect the board, then reopen Thonny.

Timed out waiting for packet header / failed to connect. Check the selected port and chip family. Hold BOOT during connection if the board requires manual download mode. Try a shorter cable and a direct USB port. Some boards use auto-reset circuitry; others require a button sequence.

Wrong boot mode or unexpected boot loop. Disconnect external wiring, verify the firmware target, and check whether a GPIO connected to external hardware affects a boot-strapping pin. If necessary, follow the official recovery procedure for the exact chip.

Thonny connects but no prompt appears. Press Enter, stop the running script, reconnect the interpreter, and check whether another program has the port. A script that continuously prints can flood the Shell.

ImportError for a module. MicroPython does not include every module available in desktop Python. Check whether the module is built into your firmware, whether a compatible library must be copied to the device, and whether its dependencies fit the available memory.

OSError or filesystem trouble. Record the full error, make a local backup of accessible files, and check available filesystem space. Do not erase the device as the first response if important scripts are stored only on it.

9. Updating, erasing, and recovering

A firmware update may fix bugs or add support, but it can also change APIs or remove assumptions your application depends on. Before upgrading a working device, save scripts locally and record the current firmware version. Read release notes and test the new build on a spare board when the application is important.

An erase operation clears the flash region specified by the tool and may remove both firmware and user files. It is useful when recovering from a damaged installation, but it is destructive. Confirm the port and target before running any erase command; accidentally selecting another serial device is a preventable mistake.

If a board appears bricked after a failed flash, disconnect peripherals, reconnect USB, enter download mode using the documented button sequence, and install the correct official image. The ROM bootloader on supported ESP32 chips normally provides a recovery route even when the application firmware is broken. Do not assume recovery is impossible merely because the REPL no longer starts.

If a board is not detected at all, flashing commands will not solve a physical USB or power problem. Inspect the connector for damage, try another known-good cable and computer, and look for operating-system device enumeration. Avoid shorting pins or applying external voltage to USB or GPIO lines as an experiment.

10. Final checklist and next steps

Before moving on to sensors or Wi-Fi, confirm all of the following:

• The chip family and firmware target match.
• The firmware came from the official MicroPython source.
• Thonny or esptool completed without a flashing error.
• The serial REPL responds to Enter and print("Hello from SolderHub").
• A short script runs and can be interrupted.
• You saved a local copy of your code.
• Any GPIO test uses a verified pinout, current-limiting resistor, and common ground.
• You know whether main.py should run automatically after reset.

Once these checks pass, continue with a small project: connect the ESP32 to Wi-Fi, scan an I²C bus, or read a sensor using a library compatible with your firmware. Add one feature at a time so you can identify which change introduces a problem. Keep Wi-Fi passwords out of public source code and never publish private network credentials in a tutorial screenshot or repository.

Official references to consult

Use the official MicroPython ESP32 documentation and download page for chip-specific firmware and board notes, the official Thonny website for installer guidance, and the Espressif esptool documentation for commands compatible with the version installed on your computer. Interfaces and command syntax can change, so the installed tool's help and the current official documentation take precedence over copied commands.

SolderHub takeaway: identify first, flash the correct image, verify the REPL, save a small script, and only then add wiring. This sequence makes installation repeatable and makes later debugging much easier.