Contents
- 0.Preface
- 1. Plugin Introduction
- 2. Plugin Installation
- 2.1 Install from PyPI
- 2.2 Install from Local File
- 2.3 Installation Precautions
- 3. Plugin Usage
- 3.1 Open the plugin management interface
- 3.2 Device Connection
- 3.3 Package Search and Download/Installation
- 3.4 View Installation Logs and Verification Results
- Attachment - Local Installation Package
- Version History
0.Preface
During the development of MicroPython, third-party driver libraries are the core dependencies for implementing functions such as sensor interaction, communication protocol, and interface control. To provide developers with a centralized and standardized package sharing platform, our team maintainsthe uPyPi repository— currently, it has included 173 various MicroPython packages, covering multiple scenarios such as sensor drivers, communication modules, and human-computer interaction, thus solving the problem of "difficulty and chaos in finding packages".

Currently, most developers still need to copy the mpremote mip install command from the repository page and then manually paste it into the terminal to execute the installation when using uPyPi packages. This process not only involves handling serial connections and command formats but also requires self-troubleshooting of dependency issues, which is very unfriendly to beginners and also reduces development efficiency.

To completely address this pain point, we developedthonny-upypi-manager, a Thonny IDE plugin that directly integrates the package management functionality of the uPyPi repository into Thonny. There's no need to open a web page to copy commands or manually handle dependencies, and the entire process from searching, viewing, caching to one-click installation can be completed within the IDE.
1. Plugin Introduction
thonny-upypi-manager is a third-party plugin we developed specifically for Thonny IDE, whose core function is to interface with uPyPi (MicroPython-style package repository) maintained by our team, enabling full-process visual management of MicroPython packages and being compatible with Thonny 4.1.7 and later versions.

Simply put, it is the "Thonny Client" for the uPyPi repository, allowing you to handle all package management operations within the IDE without having to switch web pages or copy terminal commands.

GitHub Source Code Address: https://github.com/FreakStudioCN/thonny-upypi-manager
Its functionality covers the entire process of package management and can address multiple pain points in development:
- ✅ Package Search and Metadata Viewing: Search for all packages on uPyPi directly within Thonny, and view the
package.jsoninformation (version, author, dependencies) of each package without having to switch to the web client for queries. - ✅ Local Cache Management: Supports local caching of multiple file packages. Downloaded packages will be automatically saved locally, eliminating the need for re-downloading when reused.
- ✅ One-click installation to the development board: Through the
mpremotetool, directly install the package to the/libdirectory of the connected MicroPython development board, eliminating the need for manual file copying steps. - ✅ Automatic Dependency Handling: Reads the
depsfield in thepackage.jsonof the package, automatically installs all dependencies before installing the main package, eliminating the need to manually search for dependencies one by one. - ✅ Error-friendly Prompt: When encountering issues such as network connectivity problems,
mpremotenot being configured, or the development board not being connected, clear prompts will be provided to help you quickly locate and resolve the issues.

PyPI Address: https://pypi.org/project/thonny-upypi-manager/
The source code of this plugin is maintained by Freak Embedded Studio and hosted in a GitHub repository. Currently, it is one of the most convenient MicroPython package management tools on the Thonny platform, and will continue to be updated and maintained in the future to optimize functionality and compatibility.
2. Plugin Installation
The plugin provides two installation methods: Online installation from PyPI (suitable for normal network environments, simple and fast) and Local file installation (suitable for network-restricted environments, download the installation package in advance), you can choose one according to your own situation.

First, launch Thonny IDE, click on [Tools] in the top menu bar, select [Manage Plugins...] (translated as "Manage Packages" in some versions), and you can open the plugin management window.

2.1 Install from PyPI
This is the most recommended installation method, requiring only a few steps throughout the process and no manual file handling:

In the search box of the plugin management window, enter the plugin name thonny-upypi-manager, click the [Search on PyPI] button on the right, and wait a moment to see the search results.
Note that sometimes due to network issues, the search may fail. Try searching again after a few minutes. If it still doesn't work, install it locally!

Findthonny-upypi-managerin the search results list. After clicking on it, detailed information about the plugin (version, author, dependency requirements, etc.) will be displayed. At this point, click the [Install] button at the bottom of the window to automatically complete the download and installation.

After the installation is complete, the left list of the plugin management window will appear thonny_upypi_manager , at this time you must close and reopen Thonny , the plugin can work properly.


After restarting, you will see the plugin's dedicated icon in Thonny's toolbar, indicating that the installation was successful.


2.2 Install from Local File
If your computer's network is restricted and you cannot directly download from PyPI, you can choose to download the installation package in advance and install it via a local file:
First, go to the [Attachment - Local Installation Package] to download the .whl file:
- Main Installation Package:
thonny_upypi_manager-0.1.1-py3-none-any.whl(Stable version, use first) - Backup Package:
thonny_upypi_manager-0.1.1.tar.gz(Source package, for special scenarios)


Open Thonny's [Tools] → [Manage Plugins...], find [Install from Local File] in the options area on the right side of the window, and click the corresponding link to open the file selection window.


After the installation is complete, you also need to close and restart Thonny for the plugin to load and take effect. After restarting, you can see the plugin icon on the toolbar.
After restarting, click again:

2.3 Installation Precautions
- Thonny must be restarted: After installing, upgrading, or uninstalling a plugin, Thonny needs to be restarted for the changes to take effect.
mpremotePrerequisites : After the plugin is installed, ensure that the computer has installed thempremotetool (MicroPython official serial port tool) and configured it in the system environment variables; otherwise, packages cannot be installed on the development board. You can verify the configuration success by enteringmpremote --versionin the command line.- Dependency on Automatic Processing : The plugin depends on
requests >= 2.0, and Thonny's plugin manager will automatically install this dependency without manual intervention.
3. Plugin Usage
Previously, we have completed the installation of the plugin. Next, follow the steps to start using it to manage MicroPython packages step by step. The entire process is very simple, only requiring a few steps to complete package search, download, and installation, and there is no need to manually copy files throughout, which is worry-free and efficient.
3.1 Open the plugin management interface
After restarting Thonny, you will see a new plugin icon (the one marked by the red circle) in the top toolbar. Clicking it will open the uPyPi Package Manager panel, which will be fixed on the side of the IDE for convenient subsequent operations.

3.2 Device Connection
Before starting to use, there are two preparatory steps that must be completed properly; otherwise, installation failure is likely to occur:

Connect your MicroPython development board (such as ESP32, ESP8266) to your computer using a USB cable. The plugin will automatically recognize the serial device, and the corresponding COM Port Number (such as COM55 in the example) will be displayed in the device dropdown box. If the device is not recognized, click the "Refresh Boards" button next to it to refresh, and you will be able to see the connected device.
Note that when using this plugin, Thonny's terminal cannot be connected to the device!

This is the most common pitfall for beginners: When using the plugin installation package, Thonny's terminal cannot connect to the development board! A serial device can only be occupied by one program at a time. If the terminal is currently connected to the device, the plugin cannot communicate with the device via mpremote , and will directly report an error.
The solution is simple: look at the interpreter selection in the bottom right corner of Thonny, switch it from "MicroPython (connected device status)" to "Local Python3", ensure the terminal is in a disconnected state, and then continue with the subsequent operations.
3.3 Package Search and Download/Installation
After the preparation work is completed, you can start looking for the package you need:
- Enter the package name in the search box above the panel, such as the temperature sensor driver in the example
ds18B20; - Click the "Search" button on the right, and the list below will display all matching packages, including package names, versions, authors, and function descriptions, making it easy for you to confirm whether it is the package you need.


After finding the required package, the plugin provides two handling methods, which you can choose according to your own needs:

- Download to local to view source code (Download Package): If you want to take a look at the source code of the package first, or need to modify the driver later, you can click the "Download Package" button. The package will be downloaded to the local cache directory, where you can directly view and edit the code on your computer, and then manually transfer it to the development board.
- One-click Install to Development Board (Install To Device): This is the most recommended method, fully automated: after clicking "Install To Device", the plugin will automatically perform the following operations:
- Download package files (including all files in multi-file packages);
- Automatically read
dependencies in package.json, and install all dependent libraries first; - Upload all files to the
/libdirectory of the development board via thempremotetool. The entire process doesn't require you to manually operate any step, making it very worry-free.
also supports fuzzy search:

The plugin supports fuzzy search , so even if you can't remember the full package name, you can still find relevant packages by just entering keywords. For example, just enter ds , and you can see all the driver packages related to the DS series sensors. You don't need to memorize package names by rote, making it easier to find packages.
3.4 View Installation Logs and Verification Results
During the installation process, the "Log" area below will display the operation progress in real time. You can check the current status through the log:

- For example, seeing
Searching: ds18B20"Downloading files" and other messages indicates that the plugin is working properly; - When the prompt
Installed xxx to /lib on the deviceappears, it indicates that the package has been successfully installed on the development board.

If the log content is too large and affects viewing new information, you can click the "Clear Log" button to clear the log, facilitating subsequent operations.

After installation, switch Thonny's interpreter back to MicroPython, open the file system of the development board, and you will see the newly installed package files in the /lib directory. At this point, you can directly import and use them in your code.
Attachment - Local Installation Package
thonny_upypi_manager-0.1.1-py3-none-any.whl 17 KB
thonny_upypi_manager-0.1.1.tar.gz 18 KB
Version History
Version Number | Revision Time | Modifier | Modified Content |
v1.0 | 2026-04-27 | Lee Eryong | Initial version. |