This is the documentation for the latest development branch of MicroPython and may refer to features that are not available in released versions.

If you are looking for the documentation for a specific release, use the drop-down menu on the left and select the desired version.

MicroPython libraries

Warning

Important summary of this section

• MicroPython provides built-in modules that mirror the functionality of the Python standard library (e.g. os, time), as well as MicroPython-specific modules (e.g. bluetooth, machine).

• Most Python standard library modules implement a subset of the functionality of the equivalent Python module, and in a few cases provide some MicroPython-specific extensions (e.g. array, os)

• Due to resource constraints or other limitations, some ports or firmware versions may not include all the functionality documented here.

• To allow for extensibility, some built-in modules can be extended from Python code loaded onto the device filesystem.

This chapter describes modules (function and class libraries) which are built into MicroPython. This documentation in general aspires to describe all modules and functions/classes which are implemented in the MicroPython project. However, MicroPython is highly configurable, and each port to a particular board/embedded system may include only a subset of the available MicroPython libraries.

With that in mind, please be warned that some functions/classes in a module (or even the entire module) described in this documentation may be unavailable in a particular build of MicroPython on a particular system. The best place to find general information of the availability/non-availability of a particular feature is the “General Information” section which contains information pertaining to a specific MicroPython port.

On some ports you are able to discover the available, built-in libraries that can be imported by entering the following at the REPL:

help('modules')

Beyond the built-in libraries described in this documentation, many more modules from the Python standard library, as well as further MicroPython extensions to it, can be found in micropython-lib.

Python standard libraries and micro-libraries

The following standard Python libraries have been “micro-ified” to fit in with the philosophy of MicroPython. They provide the core functionality of that module and are intended to be a drop-in replacement for the standard Python library.

• array – arrays of numeric data
• binascii – binary/ASCII conversions
• builtins – builtin functions and exceptions
• cmath – mathematical functions for complex numbers
• collections – collection and container types
• errno – system error codes
• gc – control the garbage collector
• hashlib – hashing algorithms
• heapq – heap queue algorithm
• io – input/output streams
• json – JSON encoding and decoding
• math – mathematical functions
• os – basic “operating system” services
• random – generate random numbers
• re – simple regular expressions
• select – wait for events on a set of streams
• socket – socket module
• ssl – SSL/TLS module
• struct – pack and unpack primitive data types
• sys – system specific functions
• time – time related functions
• uasyncio — asynchronous I/O scheduler
• zlib – zlib decompression
• _thread – multithreading support

MicroPython-specific libraries

Functionality specific to the MicroPython implementation is available in the following libraries.

• bluetooth — low-level Bluetooth
• btree – simple BTree database
• cryptolib – cryptographic ciphers
• framebuf — frame buffer manipulation
• machine — functions related to the hardware
• micropython – access and control MicroPython internals
• neopixel — control of WS2812 / NeoPixel LEDs
• network — network configuration
• uctypes – access binary data in a structured way

The following libraries provide drivers for hardware components.

• WM8960 – Driver for the WM8960 codec

Port-specific libraries

In some cases the following port/board-specific libraries have functions or classes similar to those in the machine library. Where this occurs, the entry in the port specific library exposes hardware functionality unique to that platform.

To write portable code use functions and classes from the machine module. To access platform-specific hardware use the appropriate library, e.g. pyb in the case of the Pyboard.

Libraries specific to the pyboard

The following libraries are specific to the pyboard.

• pyb — functions related to the board
  • Time related functions
  • Reset related functions
  • Interrupt related functions
  • Power related functions
  • Miscellaneous functions
  • Constants
  • Classes
• stm — functionality specific to STM32 MCUs
  • Memory access
  • Peripheral register constants
  • Functions specific to STM32WBxx MCUs
• lcd160cr — control of LCD160CR display
  • class LCD160CR
  • Constructors
  • Static methods
  • Instance members
  • Setup commands
  • Pixel access methods
  • Drawing text
  • Drawing primitive shapes
  • Touch screen methods
  • Advanced commands
  • Constants

Libraries specific to the WiPy

The following libraries and classes are specific to the WiPy.

• wipy – WiPy specific features
  • Functions
• class ADCWiPy – analog to digital conversion
  • Constructors
  • Methods
• class ADCChannel — read analog values from internal or external sources
• class TimerWiPy – control hardware timers
  • Constructors
  • Methods
• class TimerChannel — setup a channel for a timer
  • Methods
  • Constants

Libraries specific to the ESP8266 and ESP32

The following libraries are specific to the ESP8266 and ESP32.

• esp — functions related to the ESP8266 and ESP32
  • Functions
• esp32 — functionality specific to the ESP32
  • Functions
  • Flash partitions
  • RMT
  • Ultra-Low-Power co-processor
  • Constants
  • Non-Volatile Storage

• espnow — support for the ESP-NOW wireless protocol

Libraries specific to the RP2040

The following libraries are specific to the RP2040, as used in the Raspberry Pi Pico.

• rp2 — functionality specific to the RP2040
  • PIO related functions
  • PIO assembly language instructions
  • Classes

Libraries specific to Zephyr

The following libraries are specific to the Zephyr port.

• zephyr — functionality specific to the Zephyr port
  • Functions
  • Classes
  • Additional Modules

Extending built-in libraries from Python

Many built-in modules are actually named umodule rather than module, but MicroPython will alias any module prefixed with a u to the non-u version. This means that, for example, import time will first attempt to resolve from the filesystem, and then failing that will fall back to the built-in utime. On the other hand, import utime will always go directly to the built-in.

This allows the user to provide an extended implementation of a built-in library (perhaps to provide additional CPython compatibility or missing functionality). The user-provided module (in module.py) can still use the built-in functionality by importing umodule directly (e.g. typically an extension module time.py will do from utime import *). This is used extensively in micropython-lib. See Package management for more information.

This extensibility applies to the following Python standard library modules which are built-in to the firmware: array, binascii, collections, errno, hashlib, heapq, io, json, os, platform, random, re, select, socket, ssl, struct, sys, time, zlib, as well as the MicroPython-specific libraries: bluepy, bluetooth, machine, timeq, websocket. All other built-in modules cannot be extended from the filesystem.

Other than when you specifically want to force the use of the built-in module, we recommend always using import module rather than import umodule.

Note: In MicroPython v1.21.0 and higher, it is now possible to force an import of the built-in module by clearing sys.path during the import. For example, in time.py, you can write:

_path = sys.path
sys.path = ()
try:
  from time import *
finally:
  sys.path = _path
  del _path

This is now the preferred way (instead of from utime import *), as the u-prefix will be removed from the names of built-in modules in a future version of MicroPython.