$ git clone https://github.com/<your-user-name>/micropython
Then, configure the remote repositories to be able to
collaborate on the MicroPython project.
Configure remote upstream:
$ cd micropython
$ git remote add upstream https://github.com/micropython/micropython
It is common to configure upstream and origin on a forked repository
to assist with sharing code changes. You can maintain your own mapping but
it is recommended that origin maps to your fork and upstream to the main
MicroPython repository.
After the above configuration, your setup should be similar to this:
$ git remote -v
origin https://github.com/<your-user-name>/micropython (fetch)
origin https://github.com/<your-user-name>/micropython (push)
upstream https://github.com/micropython/micropython (fetch)
upstream https://github.com/micropython/micropython (push)
You should now have a copy of the source code. By default, you are pointing
to the master branch. To prepare for further development, it is recommended
to work on a development branch.
$ git checkout -b dev-branch
You can give it any name. You will have to compile MicroPython whenever you change
to a different branch.
Compile and build the code
When compiling MicroPython, you compile a specific port, usually
targeting a specific board. Start by installing the required dependencies.
Then build the MicroPython cross-compiler before you can successfully compile and build.
This applies specifically when using Linux to compile.
The Windows instructions are provided in a later section.
Required dependencies
Install the required dependencies for Linux:
$ sudo apt-get install build-essential libffi-dev git pkg-config
For the stm32 port, the ARM cross-compiler is required:
$ sudo apt-get install gcc-arm-none-eabi libnewlib-arm-none-eabi
See the ARM GCC
toolchain
for the latest details.
Python is also required. Python 2 is supported for now, but we recommend using Python 3.
Check that you have Python available on your system:
$ python3
Python 3.5.0 (default, Jul 17 2020, 14:04:10)
[GCC 5.4.0 20160609] on linux
Type "help", "copyright", "credits" or "license" for more information.
All supported ports have different dependency requirements, see their respective
readme files.
Building the MicroPython cross-compiler
Almost all ports require building mpy-cross first to perform pre-compilation
of Python code that will be included in the port firmware:
$ cd mpy-cross
$ make
Note that, mpy-cross must be built for the host architecture
and not the target architecture.
If it built successfully, you should see a message similar to this:
LINK mpy-cross
text data bss dec hex filename
279328 776 880 280984 44998 mpy-cross
Use make -C mpy-cross to build the cross-compiler in one statement
without moving to the mpy-cross directory otherwise, you will need
to do cd .. for the next steps.
Building the Unix port of MicroPython
The Unix port is a version of MicroPython that runs on Linux, macOS, and other Unix-like operating systems.
It’s extremely useful for developing MicroPython as it avoids having to deploy your code to a device to test it.
In many ways, it works a lot like CPython’s python binary.
To build for the Unix port, make sure all Linux related dependencies are installed as detailed in the
required dependencies section. See the Required dependencies
to make sure that all dependencies are installed for this port. Also, make sure you have a working
environment for gcc and GNU make. Ubuntu 20.04 has been used for the example
below but other unixes ought to work with little modification:
$ gcc --version
gcc (Ubuntu 9.3.0-10ubuntu2) 9.3.0
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.then build:
$ cd ports/unix
$ make submodules
$ make
If MicroPython built correctly, you should see the following:
LINK micropython
text data bss dec hex filename
412033 5680 2496 420209 66971 micropython
Now run it:
$ ./micropython
MicroPython v1.13-38-gc67012d-dirty on 2020-09-13; linux version
Use Ctrl-D to exit, Ctrl-E for paste mode
>>> print("hello world")
hello world
Building the Windows port
The Windows port includes a Visual Studio project file micropython.vcxproj that you can use to build micropython.exe.
It can be opened in Visual Studio or built from the command line using msbuild. Alternatively, it can be built using mingw,
either in Windows with Cygwin, or on Linux.
See windows port documentation for more information.
Building the STM32 port
Like the Unix port, you need to install some required dependencies
as detailed in the Required dependencies section, then build:
$ cd ports/stm32
$ make submodules
$ make
Please refer to the stm32 documentation
for more details on flashing the firmware.
See the Required dependencies to make sure that all dependencies are installed for this port.
The cross-compiler is needed. arm-none-eabi-gcc should also be in the $PATH or specified manually
via CROSS_COMPILE, either by setting the environment variable or in the make command line arguments.
You can also specify which board to use:
$ cd ports/stm32
$ make BOARD=<board> submodules
$ make BOARD=<board>
See ports/stm32/boards
for the available boards. e.g. “PYBV11” or “NUCLEO_WB55”.
Building the documentation
MicroPython documentation is created using Sphinx. If you have already
installed Python, then install Sphinx using pip. It is recommended
that you use a virtual environment:
$ python3 -m venv env
$ source env/bin/activate
$ pip install -r docs/requirements.txt
Navigate to the docs directory:
$ cd docs
Build the docs:
$ make html
Open docs/build/html/index.html in your browser to view the docs locally. Refer to the
documentation on importing your documentation to use Read the Docs.
Running the tests
To run all tests in the test suite on the Unix port use:
$ cd ports/unix
$ make test
To run a selection of tests on a board/device connected over USB use:
$ cd tests
$ ./run-tests.py -t /dev/ttyACM0
See also Writing tests.
Folder structure
There are a couple of directories to take note of in terms of where certain implementation details
are. The following is a break down of the top-level folders in the source code.
Contains the compiler, runtime, and core library implementation.
mpy-cross
Has the MicroPython cross-compiler which pre-compiles the Python scripts to bytecode.
ports
Code for all the versions of MicroPython for the supported ports.
Low-level C libraries used by any port which are mostly 3rd-party libraries.
drivers
Has drivers for specific hardware and intended to work across multiple ports.
extmod
Contains a C implementation of more non-core modules.
Has the standard documentation found at https://docs.micropython.org/.
tests
An implementation of the test suite.
tools
Contains scripts used by the build and CI process, as well as user tools such
as pyboard.py and mpremote.
examples
Example code for building MicroPython as a library as well as native modules.
Last updated on 03 Jul 2025.
Built with Sphinx using a
theme
provided by Read the Docs.
