Each CircuitPython program you run needs to have a lot of information to work. The reason CircuitPython is so simple to use is that most of that information is stored in other files and works in the background. These files are calledlibraries. Some of them are built into CircuitPython. Others are stored on yourCIRCUITPY drive in a folder calledlib. Part of what makes CircuitPython so great is its ability to store code separately from the firmware itself. Storing code separately from the firmware makes it easier to update both the code you write and the libraries you depend.

Your board may ship with alib folder already, it's in the base directory of the drive. If not, simply create the folder yourself. When you first install CircuitPython, an emptylib directory will be created for you.

CircuitPython libraries work in the same way as regular Python modules so thePython docs are an excellent reference for how it all should work. In Python terms, you can place our library files in thelib directory because it's part of the Python path by default.

One downside of this approach of separate libraries is that they are not built in. To use them, one needs to copy them to theCIRCUITPY drive before they can be used. Fortunately, there is a library bundle.

The bundle and the library releases on GitHub also feature optimized versions of the libraries with the.mpy file extension. These files take less space on the drive and have a smaller memory footprint as they are loaded.

Due to the regular updates and space constraints, Adafruit does not ship boards with the entire bundle. Therefore, you will need to load the libraries you need when you begin working with your board. You can find example code in the guides for your board that depends on external libraries.

Either way, as you start to explore CircuitPython, you'll want to know how to get libraries on board.

The Adafruit Learn Guide Project Bundle

The quickest and easiest way to get going with a project from the Adafruit Learn System is by utilising the Project Bundle. Most guides now have aDownload Project Bundlebutton available at the top of the full code example embed. This button downloads all the necessary files, including images, etc., to get the guide project up and running. Simply click, open the resulting zip, copy over the right files, and you're good to go!

The first step is to find the Download Project Bundle button in the guide you're working on.

The Download Project Bundle button downloads a zip file. This zip contains a series of directories, nested within which is thecode.py, any applicable assets like images or audio, and thelib/folder containing all the necessary libraries. The following zip was downloaded from the Piano in the Key of Lime guide.

When you open the zip, you'll find some nested directories. Navigate through them until you find what you need. You'll eventually find a directory for your CircuitPython version (in this case, 7.x). In the version directory, you'll find the file and directory you need:code.pyandlib/. Once you find the content you need, you can copy it all over to yourCIRCUITPYdrive, replacing any files already on the drive with the files from the freshly downloaded zip.

Once you copy over all the relevant files, the project should begin running! If you find that the project is not running as expected, make sure you've copied ALL of the project files onto your microcontroller board.

That's all there is to using the Project Bundle!

The Adafruit CircuitPython Library Bundle

Adafruit provides CircuitPython libraries for much of the hardware they provide, including sensors, breakouts and more. To eliminate the need for searching for each library individually, the libraries are available together in the Adafruit CircuitPython Library Bundle. The bundle contains all the files needed to use each library.

Downloading the Adafruit CircuitPython Library Bundle

You can download the latest Adafruit CircuitPython Library Bundle release by clicking the button below. The libraries are being constantly updated and improved, so you'll always want to download the latest bundle. 

Match up the bundle version with the version of CircuitPython you are running. For example, you would download the 6.x library bundle if you're running any version of CircuitPython 6, or the 7.x library bundle if you're running any version of CircuitPython 7, etc. If you mix libraries with major CircuitPython versions, you will get incompatible mpy errors due to changes in library interfaces possible during major version changes.

Download the bundle version that matches your CircuitPython firmware version. If you don't know the version, check the version info inboot_out.txt file on theCIRCUITPY drive, or the initial prompt in the CircuitPython REPL. For example, if you're running v7.0.0, download the 7.x library bundle.

There's also apy bundle which contains the uncompressed python files, you probablydon't want that unless you are doing advanced work on libraries.

The CircuitPython Community Library Bundle

The CircuitPython Community Library Bundle is made up of libraries written and provided by members of the CircuitPython community. These libraries are often written when community members encountered hardware not supported in the Adafruit Bundle, or to support a personal project. The authors all chose to submit these libraries to the Community Bundle make them available to the community.

These libraries are maintained by their authors and are not supported by Adafruit. As you would with any library, if you run into problems, feel free to file an issue on the GitHub repo for the library. Bear in mind, though, that most of these libraries are supported by a single person and you should be patient about receiving a response. Remember, these folks are not paid by Adafruit, and are volunteering their personal time when possible to provide support.

Downloading the CircuitPython Community Library Bundle

You can download the latest CircuitPython Community Library Bundle release by clicking the button below. The libraries are being constantly updated and improved, so you'll always want to download the latest bundle.

The link takes you to the latest release of the CircuitPython Community Library Bundle on GitHub. There are multiple versions of the bundle available.Download the bundle version that matches your CircuitPython firmware version. If you don't know the version, check the version info inboot_out.txt file on theCIRCUITPY drive, or the initial prompt in the CircuitPython REPL. For example, if you're running v7.0.0, download the 7.x library bundle.

Understanding the Bundle

After downloading the zip, extract its contents. This is usually done by double clicking on the zip. On Mac OSX, it places the file in the same directory as the zip.

Open the bundle folder. Inside you'll find two information files, and two folders. One folder is the lib bundle, and the other folder is the examples bundle.

Now open the lib folder. When you open the folder, you'll see a large number of.mpy files, and folders.

Example Files

All example files from each library are now included in the bundles in anexamples directory (as seen above), as well as an examples-only bundle. These are included for two main reasons:

• Allow for quick testing of devices.
• Provide an example base of code, that is easily built upon for individualized purposes.

Copying Libraries to Your Board

First open thelib folder on yourCIRCUITPY drive. Then, open thelib folder you extracted from the downloaded zip. Inside you'll find a number of folders and.mpy files. Find the library you'd like to use, and copy it to thelib folder onCIRCUITPY.

If the library is a directory with multiple.mpy files in it, be sure tocopy the entire folder to CIRCUITPY/lib.

This also applies to example files. Open theexamples folder you extracted from the downloaded zip, and copy the applicable file to yourCIRCUITPY drive. Then, rename it tocode.pyto run it.

Understanding Which Libraries to Install

You now know how to load libraries on to your CircuitPython-compatible microcontroller board. You may now be wondering, how do you knowwhich libraries you need to install? Unfortunately, it's not always straightforward. Fortunately, there is an obvious place to start, and a relatively simple way to figure out the rest. First up: the best place to start.

When you look at most CircuitPython examples, you'll see they begin with one or moreimport statements. These typically look like the following:

• import library_or_module

However,import statements can also sometimes look like the following:

• from library_or_module import name
• from library_or_module.subpackage import name
• from library_or_module import name as local_name

They can also have more complicated formats, such as including atry /except block, etc.

The important thing to know is thatanimport statement will always include the name of the module or library that you're importing.

Therefore, the best place to start is by reading through theimport statements.

Here is an example import list for you to work with in this section. There is no setup or other code shown here, as the purpose of this section involves only the import list.

import timeimport boardimport neopixelimport adafruit_lis3dhimport usb_hidfrom adafruit_hid.consumer_control import ConsumerControlfrom adafruit_hid.consumer_control_code import ConsumerControlCode

import timeimport boardimport neopixelimport adafruit_lis3dhimport usb_hidfrom adafruit_hid.consumer_control import ConsumerControlfrom adafruit_hid.consumer_control_code import ConsumerControlCode

Keep in mind, not all imported items are libraries. Some of them are almost always built-in CircuitPython modules. How do you know the difference? Time to visit the REPL.

In theInteracting with the REPL section onThe REPL page in this guide, thehelp("modules") command is discussed. This command provides a list of all of the built-in modules available in CircuitPython for your board. So, if you connect to the serial console on your board, and enter the REPL, you can runhelp("modules") to see what modules are available for your board. Then, as you read through theimport statements, you can, for the purposes of figuring out which libraries to load, ignore the statement that import modules.

The following is the list of modules built into CircuitPython for the Feather RP2040. Your list may look similar or be anything down to a significant subset of this list for smaller boards.

Now that you know what you're looking for, it's time to read through the import statements. The first two,time andboard, are on the modules list above, so they're built-in.

The next one,neopixel, is not on the module list. That means it's your first library! So, you would head over to the bundle zip you downloaded, and search forneopixel. There is aneopixel.mpy file in the bundle zip. Copy it over to thelibfolder on yourCIRCUITPY drive. The following one,adafruit_lis3dh, is also not on the module list. Follow the same process foradafruit_lis3dh, where you'll findadafruit_lis3dh.mpy, and copy that over.

The fifth one isusb_hid, and it is in the modules list, so it is built in. Often all of the built-in modules come first in the import list, but sometimes they don't! Don't assume that everything after the first library is also a library, and verify each import with the modules list to be sure. Otherwise, you'll search the bundle and come up empty!

The final two imports are not as clear. Remember, whenimport statements are formatted like this, the first thing after thefrom is the library name. In this case, the library name isadafruit_hid. A search of the bundle will find anadafruit_hidfolder. When a library is a folder, you must copy theentire folder and its contents as it is in the bundleto thelibfolder on yourCIRCUITPY drive. In this case, you would copy the entireadafruit_hid folder to yourCIRCUITPY/lib folder.

Notice that there aretwoimports that begin withadafruit_hid. Sometimes you will need to import more than one thing from the same library. Regardless of how many times you import the same library, you only need to load the library by copying over theadafruit_hid folderonce.

That is how you can use your example code to figure out what libraries to load on your CircuitPython-compatible board!

There are cases, however, where libraries require other libraries internally. The internally required library is called adependency. In the event of library dependencies, the easiest way to figure out what other libraries are required is to connect to the serial console and follow along with theImportError printed there. The following is a very simple example of anImportError, but the concept is the same for any missing library.

Example:ImportError Due to Missing Library

If you choose to load libraries as you need them, or you're starting fresh with an existing example, you may end up with code that tries to use a library you haven't yet loaded.  This section will demonstrate what happens when you try to utilise a library that you don't have loaded on your board, and cover the steps required to resolve the issue.

This demonstration will only return an error if you do not have the required library loaded into thelibfolder on yourCIRCUITPYdrive.

Let's use a modified version of the Blink example.

import boardimport timeimport simpleioled = simpleio.DigitalOut(board.LED)while True:    led.value = True    time.sleep(0.5)    led.value = False    time.sleep(0.5)

import boardimport timeimport simpleioled = simpleio.DigitalOut(board.LED)while True:    led.value = True    time.sleep(0.5)    led.value = False    time.sleep(0.5)

Save this file. Nothing happens to your board. Let's check the serial console to see what's going on.

You have anImportError. It says there isno module named 'simpleio'. That's the one you just included in your code!

Click the link above to download the correct bundle. Extract the lib folder from the downloaded bundle file. Scroll down to findsimpleio.mpy. This is the library file you're looking for! Follow the steps above to load an individual library file.

The LED starts blinking again! Let's check the serial console.

No errors! Excellent. You've successfully resolved anImportError!

If you run into this error in the future, follow along with the steps above and choose the library that matches the one you're missing.

Library Install on Non-Express Boards

If you have an M0 non-Express board such as Trinket M0, Gemma M0, QT Py M0, or one of the M0 Trinkeys, you'll want to follow the same steps in the example above to install libraries as you need them. Remember, you don't need to wait for anImportError if you know what library you added to your code. Open the library bundle you downloaded, find the library you need, and drag it to thelib folder on yourCIRCUITPY drive.

You can still end up running out of space on your M0 non-Express board even if you only load libraries as you need them. There are a number of steps you can use to try to resolve this issue. You'll find suggestions on theTroubleshooting page.

Updating CircuitPython Libraries and Examples

Libraries and examples are updated from time to time, and it's important to update the files you have on yourCIRCUITPY drive.

To update a single library or example, follow the same steps above. When you drag the library file to your lib folder, it will ask if you want to replace it. Say yes. That's it!

A new library bundle is released every time there's an update to a library. Updates include things like bug fixes and new features. It's important to check in every so often to see if the libraries you're using have been updated.

CircUp CLI Tool

There is a command line interface (CLI) utility calledCircUp that can be used to easily install and update libraries on your device. Follow the directions on theinstall page within the CircUp learn guide. Once you've got it installed you run the commandcircup update in a terminal to interactively update all libraries on the connected CircuitPython device. See theusage page in the CircUp guide for a full list of functionality