Install MicroPython on Raspberry Pi Pico and Program It with Thonny

MicroPython is a compact implementation of Python 3 that runs directly on microcontrollers. On the Raspberry Pi Pico it gives you an interactive prompt, a file system on the flash chip and modules such as machine, time and network for talking to hardware. Thonny is a free, beginner-friendly Python IDE for Windows, macOS and Linux that understands MicroPython boards: it can install the firmware, open the REPL, and copy files to and from the Pico.

In this tutorial you will put the Pico into bootloader mode, install the correct firmware, run code interactively, and save a program that starts automatically when the board is powered from a phone charger or power bank.

What You Need

Item	Notes
Raspberry Pi Pico, Pico W, Pico 2 or Pico 2 W	Any board in the family works; the firmware file differs.
Micro-USB data cable	Must carry data, not only charging current.
Computer with Thonny	Thonny 4.x or later recommended; install from the official Thonny website.

Step 1: Bootloader Mode and the UF2 File

Every Pico has a bootloader in its mask ROM that cannot be erased. When you hold down the white BOOTSEL button while plugging in the USB cable, the chip starts this bootloader instead of your program, and the board appears on your computer as a USB mass-storage drive named RPI-RP2 (RP2040 boards) or RP2350 (Pico 2 boards). Copying a .uf2 file onto that drive programs the flash, after which the board reboots automatically and the drive disappears.

MicroPython publishes separate UF2 files for each board on the MicroPython download page: one for the Pico (RPI_PICO), one for the Pico W (RPI_PICO_W), one for the Pico 2 (RPI_PICO2) and one for the Pico 2 W. The W builds include the Wi-Fi driver and the network module; a plain Pico build on a Pico W will run, but Wi-Fi and the LED will not work.

Unplug the Pico. Hold down BOOTSEL.
Plug in the USB cable while still holding the button, then release it.
A new drive appears. Either drag the downloaded MicroPython .uf2 file onto it, or let Thonny do it as described below.
The drive vanishes within a few seconds. MicroPython is now installed and a USB serial port appears instead.

Step 2: Configure Thonny

Open Thonny and go to Tools > Options > Interpreter (or Run > Configure interpreter).
Select MicroPython (Raspberry Pi Pico) as the interpreter.
Choose the port. "Try to detect port automatically" usually works; on Windows it shows as a COM port, on Linux as /dev/ttyACM0.
If the board is still in BOOTSEL mode, click Install or update MicroPython, pick the variant that matches your board, and click Install.
Click OK. The Shell pane at the bottom should print the MicroPython version and the >>> prompt.

If the Shell shows "Couldn't find the device" or similar, press the red Stop/Restart button. If that fails, check the cable, close any other program using the serial port (for example the Arduino IDE serial monitor), and try another USB port.

Step 3: Use the REPL

REPL stands for Read-Eval-Print Loop. Anything you type at >>> is executed on the Pico immediately, which is the fastest way to test a sensor or check a pin. Try these lines one at a time in the Shell:

>>> import sys
>>> sys.implementation
>>> import machine
>>> machine.freq()
125000000
>>> import os
>>> os.listdir()
[]

machine.freq() reports the CPU clock (125 MHz on an RP2040 running MicroPython, 150 MHz on an RP2350). os.listdir() lists the files stored on the Pico's internal file system, which is empty on a fresh install.

Step 4: Write and Save a Program

Type the program below in the editor. It prints board information and then counts with a timestamp, which confirms that timing and printing both work.

hello.py - first MicroPython program that prints board info and a running counter

# hello.py - first MicroPython program for the Raspberry Pi Pico family
import sys
import time
import machine

# Print basic information about the firmware and chip
print('Platform :', sys.platform)            # 'rp2' on all Pico boards
print('Version  :', sys.version)
print('CPU freq :', machine.freq() // 1_000_000, 'MHz')

# Unique 64-bit ID from the flash chip, shown as hex
uid = machine.unique_id()
print('Board ID :', ''.join('{:02x}'.format(b) for b in uid))

# Count once per second; press Stop in Thonny to end
count = 0
start = time.ticks_ms()
while True:
    elapsed = time.ticks_diff(time.ticks_ms(), start)
    print('count =', count, ' elapsed ms =', elapsed)
    count += 1
    time.sleep(1)

Press F5 (Run). Thonny asks where to save: choose Raspberry Pi Pico to store the file on the board, or This computer to keep it on your PC. Either way it runs on the Pico. Press the Stop button to interrupt the loop; this sends Ctrl+C followed by a soft reset.

Step 5: Run Automatically at Power-Up with main.py

When MicroPython boots it first runs boot.py if present, then main.py. To make a program start on its own, save it on the Pico with the exact name main.py. Now you can unplug the board from the computer and power it from any 5 V USB supply, and your code runs within a second.

Thonny's View > Files pane shows the PC on top and the Pico below. Right-click a file to upload, download, rename or delete it. This is also how you copy library files such as ssd1306.py onto the board in later tutorials.

Troubleshooting

No drive appears in BOOTSEL mode: the cable is charge-only, or the button was released too early. Hold BOOTSEL until the drive appears.
Thonny says the device is busy: another program has the COM port open. Close serial monitors and other IDEs.
ImportError: no module named 'network': you installed the plain Pico firmware on a Pico W. Reflash the W variant.
Code works from Thonny but not on battery: the file is not called main.py, or it was saved on the computer instead of the Pico.
Garbled characters: you opened the port with a baud-rate-specific terminal; USB CDC ignores baud rate, so simply reconnect.

Summary

You put the Pico into BOOTSEL mode, installed the MicroPython UF2 that matches your board, connected with Thonny, tested code at the REPL, and saved a main.py that runs automatically at power-up. You also know how to recover a board stuck in a bad program. With this workflow in place, the next tutorial uses the machine.Pin class to blink the onboard LED and external LEDs.