micropython-lib: the package repository behind import mip

What micropython-lib actually is, and who it is for

The README describes this repository as "a repository of packages designed to be useful for writing MicroPython applications". That sentence is the whole scope. It is not a runtime, not a board support package, and not a fork of CPython's standard library. It is a set of installable packages that MicroPython firmware can pull in after the fact.

The audience is narrow and specific. You are writing Python that runs on a microcontroller or on the MicroPython Unix port, and you have hit the point where the firmware's built-in modules are not enough. You want json, or collections.defaultdict, or an SSD1306 display driver, without pasting a file into your project and tracking where it came from. The repository exists so that those imports resolve the same way on every board.

The four top-level directories are the organising idea, and they map to four different promises. python-stdlib holds compatible versions of modules from The Python Standard Library, described as drop-in replacements "although many have reduced functionality or missing methods or classes". python-ecosys holds reduced-functionality versions of packages from the wider Python ecosystem, the kind of thing you would otherwise find on PyPI. micropython holds packages with no CPython equivalent: hardware drivers, bluetooth helpers, embedded-specific code. unix-ffi is only for the MicroPython Unix port, giving access to OS and third-party libraries through FFI.

That last directory is the one people misread. A unix-ffi package is not going to run on an ESP32, because the mechanism it relies on is foreign function interface calls to a host operating system. If your target is a microcontroller, treat unix-ffi as out of scope.

How mip, mpremote and manifest.py move code onto a device

There are four installation paths, and they differ in where the resolution work happens.

The first is on-device. Since MicroPython v1.20, boards with WiFi and Ethernet support ship the mip package manager, and the README's example is two lines in the REPL: import mip, then mip.install("package-name"). The device fetches the package itself. This requires a working network stack on the board, which is the constraint that rules it out for a lot of deployed hardware.

The second is host-driven. mpremote is described as the officially-supported tool for interacting with a MicroPython device, and since mpremote v0.4.0 it has a mip subcommand. You run mpremote connect /dev/ttyUSB0 mip install package-name from your PC. The package still comes over the network, but the network is your PC's, not the board's.

The third is build-time. Every package in the repository includes a manifest.py, and you pull it into your board manifest with the require() command. This is the route for firmware you ship, because the packages end up frozen into the image rather than sitting in a writable filesystem.

The fourth is a plain file copy. Many packages are single-file modules, so you copy the .py file to the device. The README's example copies python-stdlib/base64/base64.py into the device's lib directory. For packages implemented as a directory, you copy the directory instead. The README warns that this route means you "manually resolve dependencies", and points you at the relevant manifest.py to read the dependency list. That warning is the honest part of the document: the other three routes resolve dependencies for you, and this one does not.

Installing a package and using it on a board

The quickest path on a board with network access is the REPL. Run these two lines and mip fetches the package over the board's own connection.

>>> import mip
>>> mip.install("package-name")

Replace "package-name" with the package you want. If the board has no network, or you would rather drive the install from your workstation, use mpremote instead. The README gives this exact form, with the serial device and the package name as arguments.

$ mpremote connect /dev/ttyUSB0 mip install package-name

For the manual route, the README uses base64 as its worked example. The command copies the single file straight into the lib directory on the device.

$ mpremote connect /dev/ttyUSB0 cp python-stdlib/base64/base64.py :/lib

Directory-shaped packages need more than one file. The README's example is collections.defaultdict, which requires copying collections/collections/__init__.py and collections-defaultdict/collections/defaultdict.py into a directory named lib/collections on the device. Note the shape of that: the package name on the index and the module path you import are not the same string, and the README says this explicitly, using pyjwt providing the jwt module as the illustration.

If you are installing from a fork rather than the main repository, the fork owner has to opt in first, after which GitHub Actions publishes the packages to a GitHub Pages site on each push to a branch. The install command then takes an --index argument pointing at that Pages URL, and the on-device form takes an index= keyword argument. The README frames this as useful for installing packages from a pending pull request.

The reduced-functionality promise is the real limitation

The README does not hide this, but it is easy to skim past. python-stdlib packages are "compatible versions" and "should be drop-in replacements", qualified immediately by "although many have reduced functionality or missing methods or classes (which may not be an issue for most cases)". python-ecosys gets the same treatment in one word: "reduced-functionality".

That qualification is doing a lot of work, and the repository does not tell you which packages are affected or how. There is no per-package compatibility table in the README. The practical consequence is that porting code from CPython to MicroPython is not a matter of swapping the import path. A function you rely on may exist with a narrower signature, or may not exist at all, and the only reliable check is reading the package source or trying it on the device.

The second limitation is dependency resolution on the manual copy route. The README states plainly that you will need to resolve dependencies yourself and that you can inspect the relevant manifest.py to see the list. That is a manual step with no tooling described around it.

The third is the unix-ffi directory. It is scoped to the MicroPython Unix port by definition, since it exists to reach operating-system and third-party libraries through FFI. Nothing in the README suggests these packages have a microcontroller equivalent.

Where micropython-lib is the wrong tool: if you need a package that is not in the repository, or a CPython library with no reduced port here, this repository will not help you. The stated future plans include "Add support for referencing remote/third-party repositories", which is listed as a plan, not a shipped feature.

How it compares to vendoring files or using CircuitPython libraries

The obvious alternative is doing nothing: copy the .py file you need into your project and keep it in your own source tree. That gives you a file you can read, patch and pin, and it works on a board with no network and no rebuild. The cost is that updates are manual and you own the divergence. micropython-lib's answer is the manifest.py route, where require() pulls the package into your firmware build, so the code is frozen at build time but the source of truth stays upstream.

A second comparison worth drawing is with CircuitPython's library bundle. Both ship hardware drivers and stdlib-shaped modules for small Python runtimes, but the packaging model differs. micropython-lib packages are addressed by name through mip or mpremote, and each package carries a manifest.py that the MicroPython build system understands. The README's terminology section is careful about this: a library is a collection of installable packages, a package is what you install and what provides modules, and a module is what you import. The name mismatch between package and module (pyjwt providing jwt) is a deliberate part of that model rather than an accident.

Neither comparison changes the core trade-off. micropython-lib optimises for a consistent, upstream-tracked set of packages that the official tooling can install. It does not optimise for completeness against CPython, and it does not claim to.

Maintenance, licensing and the cost of staying current

The repository is not archived, and the last push was on 2026-09-22. That is recent enough that the codebase is moving, but the README gives no release cadence and no versioned release list was retrieved, so there is no published upgrade schedule to plan around. The install paths themselves are versioned against MicroPython and mpremote rather than against this repository: mip requires MicroPython v1.20 or a nightly build from October 2022 onward, and the mpremote mip command requires mpremote v0.4.0 or later. Those are the numbers that determine whether an install command will work on a given setup.

Upgrade cost depends on the route you chose. With require() in a board manifest, packages are frozen into firmware, so an update means rebuilding and reflashing. With mip or mpremote, an update is a command against a device that may already be deployed. The manual copy route has no update mechanism at all beyond copying files again.

On licensing: the README states that MicroPython is licensed under the MIT license and that all contributions should follow this license. The repository's own license field is reported as NOASSERTION, and the README's statement is about MicroPython and its contributions rather than a per-package grant. If you are shipping a product, read the LICENSE file in the repository root and the licence headers of the specific packages you vendor, since the four top-level directories may not all carry identical terms. That is a question for your own legal review, not something this article can settle.

Editorial conclusion

Adopt micropython-lib when you are writing MicroPython applications and want stdlib-shaped imports without vendoring files by hand. Do not adopt it expecting CPython parity: the README says many packages have reduced functionality or missing methods and classes. Before committing, open the manifest.py of the package you need to see its dependency list, and confirm the module name differs from the package name where the README says it can (pyjwt provides jwt). If your board has no network and you cannot rebuild firmware, plan on the manual copy route and resolve dependencies yourself.

Frequently asked questions

Official sources

1. Issues
2. micropython/micropython-lib on GitHub
3. README