Building MicroPython From Source
The prebuilt binary which can be downloaded from the MicroPython section of the documentation should serve most
use cases, but you can build your own MicroPython firmware from source if you’d like to customise its low-level
aspects.
TIP
If you have already downloaded and installed a prebuilt MicroPython UF2 file, you can skip ahead to Chapter 2 to
start using your board.
IMPORTANT
These instructions for getting and building MicroPython assume you are using Raspberry Pi OS running on a
Raspberry Pi 4, or an equivalent Debian-based Linux distribution running on another platform.
It’s a good idea to create a pico directory to keep all pico-related checkouts in. These instructions create a pico directory
at /home/pi/pico.
$ cd ~/
$ mkdir pico
$ cd pico
Raspberry Pi Pico Python SDK
1.2. Installing MicroPython on Raspberry Pi Pico 4
Then clone the micropython git repository. These instructions will fetch the latest version of the source code.
$ git clone -b master https://github.com/micropython/micropython.git
Once the download has finished, the source code for MicroPython should be in a new directory called micropython. The
MicroPython repository also contains pointers (submodules) to specific versions of libraries it needs to run on a
particular board, like the SDK in the case of RP2040. We need to fetch these submodules too:
$ cd micropython
$ make -C ports/rp2 submodules
NOTE
The following instructions assume that you are using a Raspberry Pi Pico. Some details may differ if you are building
firmware for a different RP2040-based board. The board vendor should detail any extra steps needed to build
firmware for that particular board. The version we’re building here is fairly generic, but there might be some
differences like putting the default serial port on different pins, or including extra modules to drive that board’s
hardware.
To build the RP2040 MicroPython port, you’ll need to install some extra tools. To build projects you’ll need CMake, a
cross-platform tool used to build the software, and the GNU Embedded Toolchain for Arm, which turns MicroPython’s C
source code into a binary program RP2040’s processors can understand. build-essential is a bundle of tools you need
to build code native to your own machine — this is needed for some internal tools in MicroPython and the SDK. You can
install all of these via apt from the command line. Anything you already have installed will be ignored by apt.
$ sudo apt update
$ sudo apt install cmake gcc-arm-none-eabi libnewlib-arm-none-eabi build-essential
First we need to bootstrap a special tool for MicroPython builds, that ships with the source code:
$ make -C mpy-cross
We can now build the port we need for RP2040, that is, the version of MicroPython that has specific support for our
chip.
$ cd ports/rp2
$ make
If everything went well, there will be a new directory called build-PICO (ports/rp2/build-PICO relative to the micropython
directory), which contains the new firmware binaries. The most important ones are:
firmware.uf2 A UF2 binary file which can dragged onto the RPI-RP2 drive that pops up once your Raspberry Pi
Pico is in BOOTSEL mode. The firmware binary you can download from the documentation page
is a UF2 file, because they’re the easiest to install.
Raspberry Pi Pico Python SDK
1.3. Building MicroPython From Source 5
firmware.elf A different type of binary file, which can be loaded by a debugger (such as gdb with openocd) over
RP2040’s SWD debug port. This is useful for debugging either a native C module you’ve added to
MicroPython, or the MicroPython core interpreter itself. The actual binary contents is the same
as firmware.uf2.
You can take a look inside your new firmware.uf2 using picotool, see the Appendix B in the Getting started with
Raspberry Pi Pico book for details of how to use picotool, e.g.
$ picotool info -a build-PICO/firmware.uf2
File build-PICO/firmware.uf2:
Program Information
name: MicroPython
version: v1.18-412-g965747bd9
features: USB REPL
thread support
frozen modules: _boot, rp2, _boot_fat, ds18x20, onewire, dht, uasyncio,
uasyncio/core, uasyncio/event, uasyncio/funcs, uasyncio/lock,
uasyncio/stream, neopixel
binary start: 0x10000000
binary end: 0x1004ba24
embedded drive: 0x100a0000-0x10200000 (1408K): MicroPython
Fixed Pin Information
none
Build Information
sdk version: 1.3.0
pico_board: pico
boot2_name: boot2_w25q080https://datasheets.raspberrypi.com/pico/raspberry-pi-pico-python-sdk.pdf