Adding external modules to MicroPython with Raspberry PI Pico

Last Updated on 2nd September 2023 by peppe8o

In this tutorial I’m going to show you how to include your custom, external modules in MicroPython with Raspberry PI Pico.

Importing external modules in Python is a common way to include custom functions in your code, keeping it ordered and clean. The import statement is available also in MicroPyton but requires the right files positioning to make it working with Raspberry PI Pico

The Libraries Path

A common problem for RPI Pico new users with MicroPython, when using your external .py modules, is getting errors like “ImportError: No module named”. This error claims that external modules are not located where MicroPython is expecting them. This is the easiest problem to solve. Before showing where to copy your modules, let’s understand how it works.

Unless specified differently, MicroPython looks for external modules using “sys.path” variable. This path can be shown in your Thonny IDE (please refer to my first steps with Raspberry PI Pico tutorial to get started with Thonny) with following 2 commands in your interactive shell:

import sys
sys.path

This will show something like the following:

>>> import sys
>>> sys.path
['', '/lib']

This answer means that MicroPython uses the root path (”) and its “lib” subpath (‘/lib’) as default folders where modules are to be stored. Please note that these paths refers to RPI Pico memory, so you have to store them in your board. The only exception is with built-in libraries, that are already available without explicit files and can be listed with command:

help('modules')

So, when you add to your code a import statement to include a custom library, let’s say for example a “import mylibrary”, the interpreter will look for “mylibrary” file, appending “.py” extension, in its default folders.

It will result successfull if it finds “mylibrary.py” file under root or “/lib” folder.

Showing Files and Folders with Thonny

With Thonny IDE, you can easily browse your RPI Pico and Computer folders. You can get this enabled from Thonny’s menu “View” -> “Files” option. This flag will enable the following folder three on left window side.

If Raspberry PI Pico is already connected, you will see files stored in it (“main.py” and “mylibrary.py” in following picture):

The one shown in picture is a correct external library positioning. If you have many external libraries, you can also order them within a “lib” folder (in files area, inside Raspberruy Pi Pico section, right click with mouse and use “New directory…” to create a new one).

Adding Custom Library Path

You can also add your own custom folder including modules to be enable for importing. From your shell (or from your main script, to make it persistent on each reboot) use following commands, where “mylib” can be whatever you prefer as folder name:

import sys
sys.path.append('/mylib')

Create in your Raspberry PI Pico a folder named exactly as appended on sys path.

You can now use root, lib or your custom folder (mylib in last example) for importing external modules in MicroPython:

>>> import sys
>>> sys.path
['', '/lib', '/mylib']

What’s Next

Interested to do more with your Raspberry PI Pico? Try to look at my Raspberry PI Pico tutorials for useful and funny projects!

Enjoy!