Install MicroPython on Raspberry Pi Pico W and Pico 2 W
MicroPython makes Raspberry Pi Pico-family boards approachable with a short edit-run-debug cycle. Instead of compiling a C/C++ project for every change, you can flash a MicroPython UF2 firmware file, connect with Thonny, and run Python from the REPL. The Pico W and Pico 2 W include wireless hardware, but they use different microcontroller generations and must not be treated as interchangeable firmware targets.
This guide covers identifying the board, choosing the official firmware, installing it with the BOOTSEL/UF2 method or Thonny, confirming the interpreter, saving a startup script, and resolving common connection problems. It also explains the extra checks needed before using Wi-Fi.
Important distinction: Raspberry Pi Pico and Pico W are based on RP2040, while Pico 2 and Pico 2 W use RP2350. Select firmware for the exact model. A UF2 file for the wrong board may not work, and wireless firmware builds differ from non-wireless builds.
1. Prepare the board and computer
You need the Pico-family board, a USB data cable, and a computer. A charge-only cable can power the board without transferring files, so use a known data-capable cable. Disconnect external circuits for the first installation; this removes possible shorts, power conflicts, or pin-level interference from the process.
Install Thonny from its official website if you want a graphical editor. Alternatively, the UF2 method works with a file manager and does not require a serial driver for the initial firmware copy. Use firmware from the official MicroPython download page for Raspberry Pi boards. Avoid third-party binaries unless you understand why you need them and can verify their source.
Identify the board printed on the PCB or its product documentation. The names Pico, Pico W, Pico 2, and Pico 2 W indicate meaningful hardware differences. Do not choose firmware based only on the fact that the board has a Raspberry Pi logo or a similar shape. If you have a clone, check which microcontroller it actually uses and whether its vendor provides specific instructions.
Save a copy of the downloaded UF2 file and note its version. Keeping the file name and source makes future recovery easier. Back up existing Python scripts before replacing firmware, because firmware installation or a reset may affect files stored on the device.
2. Choose the correct firmware
Open the official MicroPython downloads for Raspberry Pi microcontrollers and select the exact board family. A standard Pico build is not the same as a wireless Pico W build. Similarly, the Pico 2 family needs a compatible RP2350 build, and the W model requires firmware that supports its wireless hardware.
Read the download notes before flashing. Stable releases are generally the sensible starting point for a new project. Development builds can contain fixes or new features but may also change behaviour. If a tutorial depends on a particular module or API, check the firmware version used by that tutorial and confirm that the API still exists in the build you select.
Download the UF2 file to a folder you can find easily. Do not unzip a UF2 file or rename its extension unless the official instructions explicitly require it. A UF2 is a firmware image designed for the board's USB bootloader, not a Python script that can be copied to the filesystem after startup.
If your board is a third-party RP2040 or RP2350 design, confirm flash size and hardware details before using a generic build. Some boards have different peripherals or pin layouts. The microcontroller may be compatible while the board-level wiring is not identical to a genuine Pico.
3. Flash using BOOTSEL and UF2
- Disconnect the USB cable from the board.
- Press and hold the BOOTSEL button.
- While holding it, connect the board to the computer with USB.
- Release the button after the computer detects the bootloader drive.
- Open the newly mounted drive in the file manager.
- Copy the matching MicroPython UF2 file to that drive.
- Wait for the copy to finish. The drive normally disappears and the board restarts automatically.
The BOOTSEL drive is a special USB bootloader interface. It is not the normal MicroPython filesystem. Copying the UF2 image to this drive installs firmware; it does not mean your Python application should be stored there.
If no drive appears, try another known-good USB data cable and another port. Check that you held BOOTSEL before connecting USB, and inspect whether the operating system detects a USB device at all. On some computers, permissions or device policies can affect access, but the UF2 workflow generally avoids the serial-driver issues associated with USB-to-UART adapters.
Do not unplug the board while the file is copying. If the drive rejects the file, verify that it is the correct UF2 image rather than a ZIP archive, HTML download page, or firmware for a different microcontroller. If the board fails to start afterward, repeat the bootloader procedure and flash the correct official image.
4. Install or connect through Thonny
Open Thonny and select the MicroPython interpreter appropriate for your board. Depending on the version, the menu may refer to Raspberry Pi Pico or RP2040/RP2350. Select the serial device associated with the board. If Thonny offers a firmware installation wizard, it can help download and install the correct image; follow the options shown by your installed version.
After flashing, choose the interpreter and port, then press Enter in the Shell. A working connection should show a MicroPython banner or a prompt such as >>>. Try:
print("Hello from SolderHub")
If the shell is blank, press Enter once and reconnect the interpreter. Close other serial applications, including another Thonny window, terminal software, or IDE serial monitor, because only one program can usually own the serial port at a time.
The initial UF2 copy can succeed even when Thonny is configured for the wrong interpreter or port. Treat firmware installation and editor connection as separate steps. First confirm that the board booted, then select the right interpreter, then test the REPL. If a board is not listed, disconnect and reconnect it and inspect the operating system's device list before repeatedly reflashing firmware.
5. Run and save your first Python program
Enter a small test in Thonny:
from time import sleep
for number in range(5):
print("Pico test", number)
sleep(1)
Press Run. When prompted to save, choose the Raspberry Pi Pico device if you want the script stored on the board, or save a local copy to your computer for backup. The device filesystem and the computer filesystem are different destinations, so confirm the location in Thonny's prompt.
A file named main.py is run automatically on boot by MicroPython. Use that name only when you want the program to start every time the board resets. For initial experiments, saving as test.py and running manually can be easier to debug. Keep the source code on your computer as well, especially before updating firmware or changing the filesystem.
To stop a running program, use Thonny's stop control. If the program does not respond, reset the board and reconnect. A script with a long-running loop should include suitable delays or otherwise yield control when necessary. Avoid flooding the REPL with thousands of print statements per second; excessive serial output makes debugging harder and can slow the application.
6. Check GPIO with an LED
Pico-family GPIO uses 3.3 V logic. Do not apply 5 V to a GPIO input. For an external LED test, connect a documented GPIO through a current-limiting resistor, typically 220–1,000 ohms for a simple indicator experiment, to the LED anode; connect the cathode to GND. Verify the physical pin number against the board pinout. Physical header pin numbers are not the same thing as GPIO numbers.
Example for a pin verified on your board:
from machine import Pin
from time import sleep
led = Pin(15, Pin.OUT) # Example GPIO; verify before wiring
while True:
led.toggle()
sleep(0.5)
This code illustrates the API; GPIO 15 is an example, not a universal instruction for every external circuit. If your board has a built-in LED, its control method may differ by model and firmware. Pico W and Pico 2 W wireless-board LED hardware can differ from the original Pico, so consult the official board documentation instead of assuming the LED is connected like a non-wireless model.
Never connect a motor, relay coil, lamp, or other high-current load directly to a GPIO. Use an appropriate driver and power arrangement. If the board resets or the USB connection drops when a circuit is attached, disconnect the circuit and return to the print-only test before troubleshooting further.
7. Test Wi-Fi on Pico W or Pico 2 W
Wireless functionality requires a W model and compatible firmware. A non-wireless Pico cannot gain Wi-Fi simply by running the same Python script. Use your own 2.4 GHz network details and never commit real credentials to a public repository.
A basic connection example is:
import network
import time
SSID = "YOUR_2_4_GHZ_WIFI"
PASSWORD = "YOUR_WIFI_PASSWORD"
wlan = network.WLAN(network.STA_IF)
wlan.active(True)
wlan.connect(SSID, PASSWORD)
deadline = time.ticks_add(time.ticks_ms(), 15000)
while not wlan.isconnected() and time.ticks_diff(deadline, time.ticks_ms()) > 0:
time.sleep_ms(250)
if wlan.isconnected():
print("Connected:", wlan.ifconfig())
else:
print("Wi-Fi connection timed out")
Replace the placeholder strings locally. This bounded wait prevents the script from hanging forever if the access point is unavailable. For a production device, add a retry policy, handle credential changes, and avoid printing sensitive information. Keep in mind that network names, security settings, and signal strength can affect connection success.
If connection fails, confirm that you flashed the wireless firmware, use a compatible 2.4 GHz network where required, verify the password, and move the board closer to the access point. Some enterprise Wi-Fi networks require authentication methods that small embedded devices do not support. Test with a network you are authorized to use.
8. Common problems and fixes
BOOTSEL drive does not appear: try another data cable, connect directly to the computer, hold BOOTSEL before plugging in, and check whether the operating system detects a USB device. If the board is physically damaged, the bootloader may not be accessible.
UF2 copy fails: check available drive visibility and confirm that the file is a genuine UF2 for the exact board family. Do not copy a firmware file intended for an unrelated board.
Thonny cannot find a port: close other serial applications, reconnect the USB cable, restart Thonny, and select the device that appeared after connection. If no serial device appears, inspect the operating system's device list.
REPL shows no prompt: press Enter, choose the correct interpreter, and stop any running script. A script may be waiting, printing continuously, or repeatedly resetting the board.
ImportError: desktop Python packages are not automatically compatible with MicroPython. Look for a MicroPython-compatible library and check its dependencies and installation instructions. The firmware has limited memory and may not include every standard-library feature.
Wi-Fi module missing: verify that the board is a W model and that the firmware build supports wireless hardware. The network module and wireless APIs depend on the build.
Board repeatedly resets: remove all external wiring, use a stable USB port, and test a tiny script. Check for accidental shorts, unsuitable supply wiring, or code that raises an exception at startup. If main.py causes a boot loop, use Thonny's stop/recovery workflow or bootloader procedure to regain access and replace it with a safe test script.
9. Updating and recovering safely
Before updating firmware, copy your Python files to the computer and record the current version. Firmware changes may alter available modules, behaviour, or library compatibility. Test an update on a spare board when the project is important, and read the release notes before upgrading a working device.
If the board stops responding, try to interrupt the program and reconnect Thonny. If that fails, disconnect the USB cable, enter BOOTSEL mode, and reinstall the correct official UF2. Remember that reinstalling firmware or performing a filesystem reset may remove files saved on the device. Never rely on the board as the only copy of a project.
If the BOOTSEL drive is visible but the board does not run the expected interpreter, confirm the firmware filename and board family. If neither the serial device nor bootloader drive appears, troubleshoot the physical USB path first: cable, connector, port, and computer. Flashing software cannot fix a broken cable or damaged USB connector.
For a classroom or workshop, label boards and keep firmware downloads grouped by model. Mixing UF2 files between Pico, Pico W, Pico 2, and Pico 2 W is an easy way to waste time. A small checklist and a known-good USB cable are often more useful than repeated firmware attempts.
10. Installation checklist
- Identified the exact board: Pico, Pico W, Pico 2, or Pico 2 W.
- Downloaded the matching official MicroPython UF2.
- Entered BOOTSEL mode before connecting USB.
- Copied the UF2 and allowed the board to restart.
- Selected the correct MicroPython interpreter in Thonny.
- Confirmed the REPL with a simple
print()statement. - Ran a short program and saved a local backup.
- Verified GPIO numbering and 3.3 V electrical limits before wiring.
- Used wireless code only on a W model with compatible firmware.
What to learn next
Once the board works reliably, proceed in small steps: blink an LED, read a button, scan I²C devices, then connect Wi-Fi on a wireless model. Test each feature independently before combining them. For sensor projects, confirm the sensor's supply voltage and logic levels, and use a suitable level shifter where required. A sensor powered from 5 V may output a signal that is not safe for a 3.3 V GPIO.
Consult the official MicroPython documentation and Raspberry Pi Pico documentation for current firmware downloads, pinouts, wireless notes, and version-specific details. The Thonny interface can change, so use the instructions visible in your installed release.
SolderHub takeaway: choose firmware by the exact microcontroller and board model, use BOOTSEL/UF2 for a clean installation, verify the REPL, keep backups, and only then add hardware. This workflow makes recovery predictable and keeps simple software problems from turning into confusing hardware-debugging sessions.