Contents
- I. Project Background
- II. What benefits can uPyPi bring?
- III. Quick Installation of Driver Package
- 3.1 Preparations for Absolute Beginners
- 3.2 Basic Setup of the Development Board (Flashing MicroPython Firmware)
- 3.3 Open the uPyPi platform to search for packages and copy commands
- 3.4 Download and Install the Driver Package
- 3.5 Use the installed driver package
- IV. Uploading the Driver Package (Advanced: For Users Who Wish to Share Drivers)
- 4.1 Prepare a driver package file that complies with specifications
- 4.2 Upload the driver package to uPyPi
- 4.3 FAQ - Avoiding Version Conflicts and Duplicate Package Names
- V. Related Operation Videos
- Version History
I. Project Background

In the early days of the MicroPython ecosystem, when developers shared or used third-party libraries, they often needed to manually download multiple files and then copy them to the project directory. This "copy-paste" approach has many pain points:
- Files are easily omitted, leading to program errors
- Version chaos: it is unclear which version of the library is being used
- Dependency management is cumbersome, as you need to track down all the required dependency files on your own
- When sharing with others, you also need to package all the files, which involves complicated steps.
Later, the MicroPython community introduced the mip (short for mip installs packages) tool, which is similar to pip in Python and can automatically download and manage packages. However, its default index is micropython-lib, making it still not convenient enough for third-party libraries to be published and discovered.
Other package platforms for MicroPython similar to PyPI include mim and awesome-micropython, but both have significant drawbacks:


Accordingly, uPyPi ( https://upypi.net/ ) emerged as the times require — it is a package management repository built exclusively for MicroPython, just like "the PyPI for MicroPython", which allows developers to easily upload, share and discover driver packages, thoroughly solving the early pain points of library management.
Core Issues of the mim Platform:
- Version management mechanism: It lacks the package version freezing function, and has no basic capabilities such as version locking and dependency version constraint, making it impossible to guarantee the long-term availability of packages and dependency stability.
- Uncontrollable dependency maintenance risks: The availability of packages fully depends on the maintenance status of the original developer. If the developer stops maintenance, upgrades the project or deletes the repository, the links of the already included packages will directly become invalid, and downstream projects will be subject to cascading impacts, with no fallback or migration mechanism on the platform.
- Limited verification scope: Only the mip installability of the submitted package is checked, while core risk points such as version compatibility, long-term maintainability, and API stability are not covered.
Core Issues of the mim Platform:
- Version management mechanism: It lacks the package version freezing function, and has no basic capabilities such as version locking and dependency version constraint, making it impossible to guarantee the long-term availability of packages and dependency stability.
- Uncontrollable dependency maintenance risks: The availability of packages fully depends on the maintenance status of the original developer. If the developer stops maintenance, upgrades the project or deletes the repository, the links of the already included packages will directly become invalid, and downstream projects will be subject to cascading impacts, with no fallback or migration mechanism on the platform.
- Limited verification scope: Only the mip installability of the submitted package is checked, while core risk points such as version compatibility, long-term maintainability, and API stability are not covered.

The core issue of the awesome-micropython project:
- Merely an index collection with no verification capability: essentially, it is a linked index list of drivers and libraries, with no established validation processes for validity, compatibility or security, and thus cannot guarantee the actual usability of the included content.
- Serious lag in version compatibility: A large number of included drivers are developed based on MicroPython v1.19, while MicroPython has now been iterated to v1.27 and above, with multiple changes in core APIs, which causes the old-version drivers to fail to run properly in the new-version environment.
- Insufficient information transparency: Key information such as the maintenance status and compatible version range of the library is not marked, making it difficult for users to predict compatibility issues when using it, which may easily lead to code errors, function failure and other situations.
II. What benefits can uPyPi bring?
Using uPyPi to manage driver packages offers the following core advantages:
- ✅ One-click installation : Users only need to run a single command to automatically download and install the package along with all its dependencies, no manual file copying required.
- ✅ Controllable versions: You can specify to install packages of a specific version to avoid version conflicts.
- ✅ Automatic dependency management: The tool automatically resolves and downloads dependencies, so you don't need to find the files yourself.
- ✅ Convenient Sharing: Once uploaded to uPyPi, developers worldwide can easily find and use your driver package.
- ✅ Easy to update: When there is an update for the package, users only need to re-run the installation command to get the latest version.

Simply put, the uPyPi platform is a "hub" for MicroPython driver packages, where we can search for, view, download, and upload the driver packages we need.
Core features include:
- PyPI-like package management system: It supports the uploading, browsing, downloading and full lifecycle management of MicroPython packages, and adapts to the package management requirements of the MicroPython ecosystem.
- Standardized metadata governance: It is mandatory for packages to be accompanied by a package.json file, with core metadata such as name and version defined in a unified manner to ensure the consistency and compatibility of packages.
- Precise adaptation of hardware/firmware: supports filtering adapted packages by hardware model (e. g. RP2040) and firmware environment, solving the adaptation difficulties in different hardware/version environments.
- Multilingual and Visualized Management: It provides one-click switching between Chinese and English bilingual interfaces; the personal dashboard enables one-stop tracking and management of uploaded packages, with contribution data clearly displayed.




Other features include:
- Intelligent cache strategy optimization: First, rapidly improve the basic performance via LRU cache, then switch to the Linux PageCache solution with reference to the design concept of PostgreSQL to balance performance and system compatibility. Compared with similar platforms (such as mim without Performance optimization), the query/download response speed has been significantly improved.
- Batch Ultra-Fast Upload: Supports ZIP-format batch upload packages, with upload speed increased to dozens of times the original rate, eliminating the cumbersome and time-consuming process of uploading individual files, and is especially adapted for batch release scenarios involving large numbers of drivers/libraries.
- Precise and efficient retrieval: Newly added APIs are supported with key optimizations on the search endpoint, delivering more accurate retrieval results and faster response, which is friendly to IDE plugin extensions.
- Lightweight Development Environment: A containerized solution and local development mode are newly added, and sandbox support is restored, enabling development without complex environment configuration; GitHub binding is only required during the development phase, and there is no mandatory platform binding after launch, lowering the threshold for development and debugging.
III. Quick Installation of Driver Package
If you are new to MicroPython and the uPyPi platform, don't worry! This guide will start from the most basic preparation steps, and walk you through step by step how to download and use driver packages from the uPyPi platform on Raspberry Pi Pico 2 (without network) and Pico 2 W (with network), taking the bmp280_driver barometric pressure and temperature sensor driver as an example. It will also briefly explain how to upload driver packages for users who have the need to share them.
3.1 Preparations for Absolute Beginners
Before using uPyPi, you need to prepare the hardware and software, and complete the basic setup, all of which are indispensable.
3.1.1 Hardware Preparation
| Hardware Name | Purpose | Notes |
|---|---|---|
| Any microcontroller that supports mpy firmware, with or without network connectivity Here, we use the Raspberry Pi Pico2 or Pico2W | Core hardware that runs the MicroPython code | Pico2 has no WiFi (local installation required); Pico2W has WiFi (remote installation possible) |
| USB-C data cable | Connects the development board to the computer; transfers code / supplies power | Must support data transfer (charge-only cables do not work) |
| BMP280 barometric pressure and temperature sensor module (optional) or other common electronic modules | Hardware for testing the driver package | Used to verify that the installed bmp280_driver works |
| Dupont wires (several) | Connect the development board to the sensor | Prepare male-to-male / male-to-female Dupont wires, chosen according to wiring needs |
3.1.2 Software Preparation
- Install the Thonny editor:
Thonny is the most suitable MicroPython development tool for absolute beginners, supporting code writing, development board connection, and file management.
- Download Link: https://thonny.org/
- Installation method: Just follow the on-screen prompts to proceed with the installation step by step (no modification to the default settings is required).
- Install the mpremote tool (for the computer side)
This is a tool for communication between a computer and a MicroPython development board, used to install driver packages locally (a necessity for microcontrollers that do not support networking functions).
Open the "Command Prompt (CMD)" or "PowerShell" on your computer, enter the following command and press Enter:
pip install mpremoteWhen the prompt "Successfully installed mpremote" appears, the installation is completed successfully.
3.2 Basic Setup of the Development Board (Flashing MicroPython Firmware)
You need to first flash an mpy firmware to your MCU. Here we take Raspberry Pi Pico2 / Pico2W as an example: they do not come with MicroPython firmware from the factory, so you have to flash it first before using them.
- Press and hold the BOOTSEL button on the development board, then connect the board to your computer via a USB-C cable while holding the button, and finally release the button.
- The computer will recognize a USB flash drive named "RPI-RP2".
- Open your browser and download the corresponding firmware:
- Raspberry Pi Pico 2 Firmware: https://micropython.org/download/RPI_PICO2/
- Firmware for Raspberry Pi Pico 2W: https://micropython.org/download/RPI_PICO2W/
- Copy the downloaded
. uf2firmware file and paste it into the "RPI-RP2" USB drive. - After the copying is complete, the development board will restart automatically, the USB flash drive will disappear, and the firmware flashing is now finished.
3.3 Open the uPyPi platform to search for packages and copy commands
The uPyPi platform serves as a "hub" for MicroPython driver packages, where we can search for, view, and download the driver packages we need.

Open your browser and go to the official uPyPi website: https://upypi.net/
In the search box at the top of the page, enter bmp280 and click the "Search" button on the right:

The search results will display matching driver packages (e. g., bmp280_driver 1.0.0), which you can click to use:

On the driver package details page, you can switch the driver package version on the left side of the page:

The core installation commands (local installation / remote installation) will be displayed on the left side of the page:

3.4 Download and Install the Driver Package
Depending on whether the development board has network connectivity, it is divided into local installation (Pico2) and remote installation (Pico2W) two methods.
3.4.1 Local Installation (for development boards without WiFi)
Connect the device to a computer via USB, then use the mpremote tool to install the driver package from uPyPi onto the development board.
Enter execution command:
mpremote mip install https://upypi.net/pkgs/bmp280_driver/1.0.0Wait for the command to execute; when the following content appears in the terminal, the installation is successful:

We can also use the following command to check the files on the board and confirm whether the download is successful:
# View the root file directory
mpremote fs ls
# View the directory under the 'lib/' folder
mpremote fs ls 'lib/'
3.4.2 Remote Installation (for development boards with WiFi)
First connect the development board to WiFi, then install the driver package directly in the REPL terminal of the development board.
- First, connect the Raspberry Pi Pico W 2 to your computer via a USB cable. Once Thonny automatically recognizes the device, click the "Shell" panel at the bottom.
- If the Shell panel displays
>>>, it indicates that the REPL interactive mode of MicroPython has been entered; if other content is displayed, press "Ctrl + D" to restart the development board, and you will see>>>.
After the >>> in the Shell panel, enter the following lines of code one by one (replace with your WiFi name and password), and press Enter after each line:
import network
wlan = network.WLAN(network.STA_IF)
wlan.active(True)
wlan.connect("你的WiFi名称", "你的WiFi密码")
# Wait for connection to succeed
import time
while not wlan.isconnected():
print("Connecting to WIFI...")
time.sleep(1)
print("WIFI Connected! IP Address:", wlan.ifconfig()[0])If "WIFI Connected! IP Address: 192.168.xx.xx" is displayed, it indicates that the WiFi connection is successful:

In the Shell panel, after >>>, enter the following complete installation command:
import mip
mip.install("https://upypi.net/pkgs/bmp280_driver/1.0.0")After the execution is completed, if the following content is displayed, the installation is successful:

Click "Raspberry Pi Pico2" in the "Files" panel on the left, expand the "lib" folder, and if you can see bmp280_float.py file, the installation is successful:


3.5 Use the installed driver package
After the installation is complete, we use the BMP280 sensor to test whether the driver package works properly. For this part, just refer to the cloud document below:

https://freakstudio.cn/node/019ba20b-b702-7118-a3b3-c3fb7218fd61
IV. Uploading the Driver Package (Advanced: For Users Who Wish to Share Drivers)
If you have developed your own MicroPython driver and wish to share it on uPyPi for others to use, you can follow the steps below (taking bmp280_driver as an example).
4.1 Prepare a driver package file that complies with specifications
The file directory of the driver package must follow the structure below (refer to Figures 6-9), and none of the required components can be missing:
你的驱动包文件夹(如 bmp280_driver)/
├── code/ # Folder holding the core driver code
│ ├── 驱动核心文件.py(如 bmp280_float.py)
│ └── 测试示例文件.py(如 main.py,可选)
├── package.json # The driver package's "ID card" (required file)
├── README.md # Driver usage instructions (recommended file)
└── LICENSE # Open-source license file (recommended file)

package.json is the core configuration of the driver package and must contain the following required fields; you can also add optional fields to enrich the information:
{
"name": "bmp280_driver", // Package name, lowercase, separated by underscores
"version": "1.0.0", // Version number, following the major.minor.patch rule
"urls": [ // File mapping: ["device-side file name", "local file path"]
["bmp280_float.py", "code/bmp280_float.py"]
],
"description": "控制 BMP280 气压温度传感器的 MicroPython 驱动", // Optional: description
"author": "你的名字", // Optional: author
"license": "MIT", // Optional: license
"keywords": ["micropython", "bmp280", "传感器"] // Optional: search keywords
}4.2 Upload the driver package to uPyPi
4.2.1 Local Upload

Make sure your project root directory contains the following files (no nested folders, placed directly in the root directory):
code/: Driver code folderLICENSE: License Filepackage.json: Package configuration file (must contain thenameandversionfields)README.md: Package description document
⚠️ Key Requirement: No extra folders shall be nested inside the ZIP package, all files must be placed directly in the root directory of the Compressed Packet (refer to the example structure:
BH1750_driver.zip→ directly containscode/,package.jsonand other files).

Next, package the library file into a ZIP Compressed Packet:
- Select all files in the project root directory (
code/,LICENSE,package.json,README.md). - Right-click → select "7-Zip" → "Add to Compressed Packet"(or directly select "Add to [package name]. zip").
- In compression settings:
- Compression Format Selection
zip - It is recommended that the file name be consistent with the package name (e. g.
BH1750_driver.zip) - Confirm that the path mode is set to "relative path" to avoid generating nested directories
- Compression Format Selection
- After generating the ZIP package, check its internal structure: open the ZIP file to confirm that all files are directly stored in the root directory without any extra folder nesting.


Visit the official uPyPi website, click the "Log in with GitHub" button in the top right corner, and log in with authorization via your GitHub account:

After logging in, click "My Panel" at the top, then click "Click here to upload your first package":

Go to the upload page, click "Select File", and select the ZIP package you just generated:

Confirm that the folder contains package.json, then click the "Upload Package" button and wait for the upload to complete:



Once uploaded successfully, your driver package will be searchable on uPyPi and can be installed directly by other users.
4.2.2 Github URL Upload
Submitting the driver package directly via the GitHub repository address is a convenient upload method suitable for open-source projects. The operation steps are as follows:

Ensure that the code of your driver package has been hosted on a GitHub repository and complies with the following specifications:
- The target directory (the repository root directory or a subdirectory) must contain the
package.jsonfile, which needs to define thename(package name) andversion(version number) fields; - The total file size of the driver package shall not exceed 10 MiB;
- The target directory does not contain symbolic links (soft links / hard links).

Go to your GitHub repository page, click the green "Code" button, and copy from the pop-up options the HTTPS-formatted repository URL (e. g. https://github.com/FreakStudioCN/uPyPI_Test_Package.git ).

In the "Upload Driver Package" module of the uPyPi platform, enter the "GitHub URL Upload" interface, open the "Submit Package from Git Repository" form, and fill in the following information in sequence:
- Git Repository URL: Paste the HTTPS address of the GitHub repository you just copied;
- Branch: Enter the name of the branch from which you want to pull code; the default entry is
main(if the default branch of your repository ismaster, you need to modify it to the corresponding branch name); - Target Folder List: Enter the directory path where the driver package is located (separate multiple paths with English commas); leaving it blank means pulling the entire repository. The example entry
src, libindicates that only files under the two directoriessrcandlibwill be uploaded.

Read the "Submission Requirements" below the form carefully, confirm that your repository fully complies with the specifications, and then click the "Submit Package" button.

The platform will automatically pull the code of the specified directory from the GitHub repository to complete the parsing and publishing of the driver package:
- If the submission is successful, the page will display the prompt "Upload successful";
- You can view the newly uploaded driver package in the list under "My Panel → My Uploaded Packages", and verify that information such as the package name and version number is correct;
- Once the upload is complete, other uPyPi users can directly install and use your driver package by searching for the package name.
4.3 FAQ - Avoiding Version Conflicts and Duplicate Package Names

When uploading a driver package to uPyPi, you may encounter a prompt like the one shown in the image:"The package bmp280_driver version 1.0.0 already exists". This is because the uPyPi platform has strict rules for package management to ensure that the version and name of each package are unique, making it convenient for users to install and use them accurately.
uPyPi does not allow uploading the same package name with an exactly identical version number. This is just like the update log of a mobile app:
- Every time you fix a minor bug or optimize code, you need to update the version number (e. g., from
1.0.0→1.0.1). - If the version number remains unchanged, the platform will consider that you are repeatedly uploading the same package and thus reject the operation.
Version numbers follow the "major.minor.patch" convention (Semantic Versioning) and must be incremented with each upload:
- Revision number (the third digit): for fixing minor bugs and optimizing code details, e. g.
1.0.0→1.0.1. - Minor version (second digit): adds new features and supports new hardware, for example,
1.0.1→1.1.0. - Major version (the first digit): for major overhauls that are incompatible with legacy code, e. g.,
1.1.0→2.0.0.
If your package name is too broad (for example, sensor_driver), it will easily conflict with packages from other developers, causing confusion for users during installation. It is recommended to follow the rules below:
- Package names should be specific: include the hardware model or functions, for example,
bmp280_driver(clearly indicating it is the driver for the BMP280 sensor), rather thansensor_driver. - Format requirements: all in lowercase, use underscores
_to separate words, avoid spaces and special characters. - Advance Search Verification: Enter the name of the package you intend to use in the search box on the homepage of uPyPi, and confirm that there is no duplicate name before using it.
Steps to resolve when you encounter the "version already exists" prompt:
- Open the
package.jsonfile of the driver package, and modify theversionfield to the new version number (e. g.,1.0.1). - Save the file and make sure that the file name and content remain unchanged.
- Return to the uPyPi upload page, reselect the driver package folder, and click "Upload Package".
- If the prompt "Upload successful" appears, the version update is complete; if an error prompt still appears, check whether the package name is duplicated or whether the version number has indeed been incremented.
V. Related Operation Videos
Version History
Version Number | Revision Date | Modifier | Modified Content |
v1.0 | 2026-02-25 | Lee Eonyong | Initialization version. |
v1.1 | 2026-03-02 | Lee Eonyong | Add the English version of this document: Instructions for Downloading and Uploading Driver Packages on the uPyPi Platform |
v1.2 | 2026-03-16 | Lee Eonyong | Updated some content, the package upload method, and the operation video. |
v1.2.1 | 2026-03-17 | Lee Eonyong | Updated some of the images. |
v1.3 | 2026-03-23 | Lee Eonyong | Added 4.2.2 Github URL upload feature. |