MicroPython

Download
and setup

The tools, then Thonny, then the firmware your board needs.

tools

A few programs can put Python on a board and then talk to it. Thonny is the easiest of them and the one used below. The rest are worth knowing about.

Thonny

A Python IDE for beginners, written by Aivar Annamaa. It ships its own Python, has an editor, a debugger and a variable inspector, and it installs MicroPython firmware onto a board for you.

Use it if you have never programmed a microcontroller, or you want one program that both writes code and flashes firmware.

MIT licensed, free, and runs on Windows, macOS and Linux. This is the tool the steps below use.

MicroPython REPL

The prompt built into the firmware itself. Connect over serial and type Python lines, one at a time, straight into the board.

Use it if you only need to check that a sensor reads, or to try two or three lines without installing anything.

Already on the board once firmware is flashed. No install needed.

rshell

A command line tool that mounts a board's filesystem as a drive and copies files in and out, in the style of Unix commands.

Use it if you already edit code in another editor and just want to upload a file.

Install with pip install rshell. Needs one line added to boot.py to accept commands.

ampy

Another command line uploader, from the same author as MicroPython itself. Talks to the REPL rather than mounting a filesystem.

Use it if you prefer ampy put to a GUI, or you are scripting the upload.

Install with pip install ampy.

esptool

The flash tool from Espressif. Writes firmware, erases flash, and reads chip information over the serial port.

Use it if the board will not enumerate, or you need to erase flash before a reflash.

Install with pip install esptool. Also what Thonny calls behind the scenes on ESP32.

mpremote

The command line tool that ships with MicroPython itself. Runs code on the board, copies files, and manages the device.

Use it if you want one tool that covers running, copying and resetting without an IDE.

Install with pip install mpremote. Comes with the micropython package too.

Code

Thonny's own editor, split out as a standalone app. Saves straight to a board over serial.

Use it if you want a lighter editor than the full IDE, on Linux or as a Flatpak.

Free and open source.

uPyLoader

A small utility for copying files onto a board and running scripts, with a plain file listing.

Use it if rshell or mpremote will not talk to your board and you want something older and simpler.

Open source, largely superseded but still working on some ports.

download thonny

Get it from thonny.org. The download box is at the top of that page, and it offers a different file for each system. Thonny 5.0.0 is the current release.

windows

  1. Open thonny.org and find the Windows panel.
  2. Download thonny-5.0.0-x64.exe for a normal Intel or AMD PC. For a Snapdragon or other Arm machine, take thonny-5.0.0-arm64.exe instead. Both need Windows 10 or 11.
  3. Run the installer and accept the defaults. It bundles Python 3.14, so there is nothing else to install first.

macos

  1. On the same page, find the Mac panel.
  2. Download thonny-5.0.0-x64.pkg for an Intel Mac, or thonny-5.0.0-arm64.pkg for Apple Silicon.
  3. Open the package and drag Thonny into your Applications folder.

linux

  1. The Linux panel gives a one line installer that uses your existing Python 3:
thonny installer 
wget -qO- https://thonny.org/installer-for-linux | bash
  1. If you would rather not run a piped script, install from your own package manager instead:
alternatives 
# from the system repositories
sudo apt install thonny          # debian, ubuntu, mint, raspbian
sudo dnf install thonny          # fedora

# or straight from pypi, into your own python
pip3 install thonny

download the firmware

A board ships with some firmware of its own, usually the manufacturer's. MicroPython is a different firmware, so it has to be downloaded and written to the board once. Thonny can do the writing, but you still have to fetch the right file.

find the right file

  1. Go to micropython.org/download.
  2. Pick your port from the first filter. The port is the chip family, not the board: ESP32, ESP8266, rp2 for the Raspberry Pi Pico, samd, stm32, nrf, and the rest.
  3. Narrow it with MCU if you know it. For a Pico that is rp2040, for a Pico 2 it is rp2350, for most ESP32 boards it is esp32.
  4. Find your board in the list. The page builds are dated, so a newer one may be listed since this page was written. A board with no build means you will have to compile firmware yourself.
  5. Download the binary. The filenames give it away: firmware-esp32-*.bin for ESP32, firmware-rp2-pico-*.uf2 for the Pico, and firmware.bin for many STM32 boards.
where files usually go 
# esp32 and esp8266, any .bin
~/Downloads/firmware-esp32-1.29.0.bin

# raspberry pi pico, a .uf2 you drag onto the board
~/Downloads/firmware-rp2-pico-1.29.0.uf2

# pyboard and other stm32
~/Downloads/firmware.bin

set up thonny

Start Thonny, plug the board in with a data USB cable, and tell Thonny which interpreter to use. A data cable matters: a charge-only cable powers the board and nothing more.

one time interpreter setup

  1. Open Thonny. The welcome screen offers a quick link to the interpreter settings, or use Tools → Options.
  2. Go to the Interpreter tab.
  3. Set Language to MicroPython (generic). Thonny also lists port specific entries, such as MicroPython (ESP32/ESP8266), which set up a few extras for you.
  4. In the Port dropdown, pick your board. If it is not listed, leave it on auto and Thonny will scan for it.
  5. Click OK.

install the firmware

  1. Put the board into its flashing mode. On most boards hold BOOT or GPIO0 while plugging it in, then release. On a Pico, hold BOOTSEL. The pyboard has no special mode: the port appears on its own.
  2. Back in Tools → Options → Interpreter, press Install or update MicroPython.
  3. Choose Local and browse to the binary you downloaded in the previous section. The Remote option fetches firmware over the network instead, which is convenient but slower and gives you less control over the version.
  4. Select the port again if Thonny cleared it, then press Install.
  5. Wait for the write to finish. On an ESP32 the progress bar is followed by a hash check, which takes a minute or two. Unplug and replug the board when it is done.

check it worked

  1. Press the green Run button, or F5. Thonny switches to the Shell pane and you get a prompt beginning with >>>. That is the MicroPython REPL, running on the board.
  2. Type a line and press enter:
first check 
>>> import sys
>>> sys.implementation
MicroPython v1.29.0 ... on ESP32
>>> uname()
sysname='esp32', releaselevel='candidate'
  1. Anything other than an error means the firmware is in place and the board is talking to your computer.
  2. Now type in the editor pane and press Ctrl+S to save straight to the board. Saving to the device, rather than to your own disk, is what makes the program run on boot.

if the port does not show up

  • a charge-only cable

    The most common cause. Many USB cables carry power and no data, and the board is then invisible.

  • a missing driver

    Windows needs the CP210x or CH340 driver for older boards. The Pico needs nothing extra.

  • another program has the port

    A serial monitor, Arduino IDE or terminal already open on that port will block Thonny. Close it.

  • firmware already installed

    Once MicroPython is on the board it enumerates differently. Hold BOOT and replug so it comes up as a fresh drive instead of a serial port.

next

With a working prompt, the library reference covers what the standard modules give you, and boards lists what else runs MicroPython. A first program is a handful of lines:

main.py 
import machine
import time

# pin 1 is the green led on a pyboard
led = machine.Pin(1, machine.Pin.OUT)

while True:
    led.on()
    time.sleep_ms(200)
    led.off()
    time.sleep_ms(200)

Save that as main.py on the board. It runs every time the board boots, which is what boot.py is for: one time setup, before main.py.