Extending built-in libraries from Python
A subset of the built-in modules are able to be extended by Python code by
providing a module of the same name in the filesystem. This extensibility
applies to the following Python standard library modules which are built-in to
the firmware: array, binascii, collections, errno, gzip,
hashlib, heapq, io, json, os, platform, random,
re, select, socket, ssl, struct, time zlib, as well
as the MicroPython-specific machine module. All other built-in modules
cannot be extended from the filesystem.
This allows the user to provide an extended implementation of a built-in library
(perhaps to provide additional CPython compatibility or missing functionality).
This is used extensively in micropython-lib, see Package management for
more information. The filesystem module will typically do a wildcard import of
the built-in module in order to inherit all the globals (classes, functions and
variables) from the built-in.
In MicroPython v1.21.0 and higher, to prevent the filesystem module from
importing itself, it can force an import of the built-in module it by
temporarily clearing sys.path during the import. For example, to extend the
time module from Python, a file named time.py on the filesystem would
do the following:
_path = sys.path
sys.path = ()
try:
from time import *
finally:
sys.path = _path
del _path
def extra_method():
The result is that time.py contains all the globals of the built-in time
module, but adds extra_method.
In earlier versions of MicroPython, you can force an import of a built-in module
by appending a u to the start of its name. For example, import utime
instead of import time. For example, time.py on the filesystem could
look like:
from utime import *
def extra_method():
This way is still supported, but the sys.path method described above is now
preferred as the u-prefix will be removed from the names of built-in
modules in a future version of MicroPython.
Other than when it specifically needs to force the use of the built-in module,
code should always use import module rather than import umodule.
Last updated on 04 Aug 2025.
Built with Sphinx using a
theme
provided by Read the Docs.
