Circup is a software utility that makes it easy to install and update the libraries in the lib folder on your CircuitPython devices. It can install new libraries, and also determine if any libraries need updating and perform that updating.

Circup was originally written by Nicholas Tollervey.

This kind of utility is especially useful with some of our M4 CircuitPython devices that can handle lots of libraries such as the Adafruit Grand Central M4 Express.

The PyPortal is packed with so many features, that it uses a lot of libraries, making this tool especially useful.

Our PyGamer and PyBadge also use quite a few libraries.

Another very popular option is the Adafruit Feather M4 Express.

If you would like something in between, you can go with the Adafruit Metro M4 Express.

If you need a Metro M4 that can also do WiFi, you may like the Adafruit Metro M4 Express Airlift Lite.

Requirements

You will need to have Python 3.9 or higher, pip, and git installed in order to install circup.

Windows Installation

You can verify that you have Python correctly installed by typing python3 --version at the command prompt and checking that you are running Python 3.9 or higher. If you have Windows 10 and don't currently have it installed, Python is available in the Windows store.

Next, we check that Pip is installed by typing pip3 --version. This should have been installed with Python, but if not, you will need to download and install it. Make sure you are running the latest version of pip by typing pip3 install --upgrade pip.

Finally, make sure git is installed by typing git --version. If this isn't installed, you will need to install a version that you can run from the command line such as git-scm.

After we have verified that we have all the requirements, let's update the Path variable. Getting to this can vary by windows versions, but it's often in the Environment Variable setting dialog, which can be accessed through the System Properties.

To figure out the correct path to add, type the following at the command line:

python3 -m site --user-base

Then copy the path that is returned and add \Python312\Scripts or whatever the latest version is onto the end of your PATH. If your PATH varies due to having a different version of Python, change it accordingly.

Now continue on to the circup installation.

MacOS Installation

You can verify that you have Python correctly installed by typing python3 --version at the command prompt and checking that you are running Python 3.9 or higher. If you don't currently have it installed, Python can easily be installed through a utility called Homebrew.

Next, we check that Pip is installed by typing pip3 --version. This should have been installed with Python, but if not, you will need to download and install it. Make sure you are running the latest version of pip by typing pip3 install --upgrade pip.

Finally, make sure git is installed by typing git --version. If this isn't installed, this can also easily be installed with Homebrew.

Now continue on to the CircUp installation.

Linux Installation

You can easily make sure all three requirements are installed with the following command on a Debian or Ubuntu system:

sudo apt-get install -y python3 git python3-pip

Make sure you are running the latest version of pip by typing pip3 install --upgrade pip.

Now continue on to the CircUp installation.

Python VENV

You will need to setup a venv with modern python3 releases. The activate file will need to be sourced on each subsequent login for circup to work. 

After we have verified that we have all the requirements, it's time to install CircUp. Now that it's on PyPI, installation is a snap. Just open up the command line and type the following:

That's it. After that type circup --version and it should return the version that it's running on. If it returns the version successfully, you should be good to go.

Upgrading to the latest Version

If you already have an older version of CircUp installed through PyPI, you can update to the latest version by typing:

Contributing

The utility is still growing and you can check out the GitHub Repo for any outstanding issues. Everyone is welcome to submit Issues and Pull Requests to the Circup Repository to request features or fix bugs.

Let's Go!

Once you have Circup installed, using it involves just typing a few of the available commands:

• install - Install a named module(s) onto the device.
• uninstall - Uninstall a named module(s) from the connected device.
• update - Update modules on the device.
• list - Lists all out of date modules found on the connected device.
• freeze - Output details of all the modules found on the connected.
• example - Copy named example(s) from a bundle onto the device.
• show - Show a list of available modules in the bundle.
• bundle-add, bundle-remove, bundle-show - Manage local bundles.

Argument / Command Order

Except for the --help argument, every other argument that is documented on this page needs to be passed prior to the command being being issued. 

Correct Examples (Arguments Before Command):

Incorrect Examples (Arguments After Command):

Informational Commands & Arguments

The following commands do not interact with a microcontroller. They can be used without a device plugged in.

• circup --help : Print the built-in documentation information into the terminal. If you don't specify any command then it will print an overview of all commands along with the general documentation
• circup [command] --help : Print the built-in documentation about the specified command i.e. circup install --help will print documentation and available arguments for the install command.
• circup --version : Print current version of the Circup utility that is installed.
• circup --verbose [command] : Print more verbose output when executing the specified command. Without the --verbose flag specified there is still more verbose information written to a log file, this flag prints that information to the terminal output in addition to the log file.

Web Workflow Arguments

The following arguments are used for interacting with a Circuitpython device via Web Workflow rather than the typical USB Disk Workflow. To connect to the web workflow two things are needed: the hostname or IP address of the device, and the web workflow password that is used to authenticate the requests. Optionally a timeout can be passed to configure how long the tool will wait while attempting to make a connection to the device.

• --host [hostname_or_ip] : The IP or Hostname of the CircuitPython device to connect to. If omitted Circup will attempt to use circuitpython.local and find unique hostname from the information returned by the workflow API. If there are multiple devices with web workflow enabled connected to the network then you'll need to specify one with this argument. examples:
  • circup --host 192.168.1.188 [rest of command]
  • circup --host cpy-59689c.local [rest of command]
• --password [password_value] : The password used to authenticate the web workflow requests. This is configured in settings.toml on the device. example:
  • circup --host 192.168.1.188 --password Passw0rd [rest of command]

  Alternatively you can set the environment variable CIRCUP_WEBWORKFLOW_PASSWORD with a value equal to the password. Circup will check for this environment variable and attempt to use it's value if it exists. If it doesn't exist, or if the value inside of it is incorrect then the --password argument is required to be passed with the correct password in order for Circup to function correctly. After setting the environment variable you can omit the --password argument from circup commands for the remainder of the terminal session example (Linux / Mac):

  • export CIRCUP_WEBWORKFLOW_PASSWORD=Passw0rd 
• --timeout [value] : The number of seconds to wait while attempting to connect to the Circuitpython device over the network. The default values is 30 seconds. example setting to 10 seconds:
  • circup --timeout 10 [rest of command]

Disk Path Location Argument

If you have changed your USB Storage device's label to something other than the default CIRCUITPY or if you'd like to use circup to manage libraries in a local project directory instead of directly on a circuitpython device you can use the --path argument.

• --path [path_value] : A local filepath pointing the local directory that you would like circup to treat as it would the circuitpython device root for the purposes of managing library files. Examples:
  • circup --path CUSTOMDRIVENAME/ [rest of command]
  • circup --path ~/projects/very_cool_project/ [rest of command]
  • circup --path c:\projects\very_cool_project\ [rest of command]

Local Project Directories

If you are using circup to manage libraries within a local project directory on your host PC rather than directly on a Circuitpython device you will also need to pass the --cpy-version argument with a value equal to a valid semantic version string that circup will use when determining which version of MPY file to load.

• --cpy-version [version] : The version number to use for the purpose of selecting MPY version of the library files. Example:
  
  • circup --path cool_project/ --cpy-version 9.0.0 [rest of command]

Troubleshooting

Possible Error Output:

Explanation

Circup was unable to automatically locate your device. There are a few possible causes of this.

If your device is connected with a USB cable then ensure that it is appearing to the host PC as the CIRCUITPY drive. If it's not appearing, make sure that you have a working USB cable with data lines. Some USB cables are charging only, and will not work with Circup.

If your device has a custom drive name other than CIRCUITPY then you will need to use the --path argument and pass the path pointing to your drive by it's name.

If your using web workflow then you need to include the --host and --password arguments and pass in the IP address or hostname, and webworkflow password respectively.

The circup install command is used to install the specified libraries onto the connected device.

Options Details

There are several options specific to the install command that can be used to control it's behavior.

• --help : Print the built-in documentation of the install command (shown above).
• --py : Load the .py version of the module(s) instead of the .mpy ones. This is helpful if you want to be able to look at the clear text python code for the library for troubleshooting or development purposes. Or if you are testing an awkward core version that has restricted support for mpy versions.
• -r [file], --requirement [file] : Instead of listing module(s) on the command line read them from a text file, typically requirements.txt. The requirements listed in this file can be pypi names like adafruit-circuitpython-display-text or "import names" like adafruit_display_text.
• -a, --auto : Automatically look for dependencies inside of code.py or the specified auto-file instead of passing module(s) by command line. It will find any libraries imported within the file then install them.
• -u, --upgrade : Force the newly installed library to overwrite the previously installed instance. By default circup will print an error and not overwrite libraries that are already installed. This flag indicates the user wishes to overwrite any existing library versions that are found. The existing libraries are deleted, so be careful if you're modifying your libraries, make sure you backup any important versions!
• --auto-file [file] : Specify the file to use with -a, --auto. If it is not specified then code.py is used by default.

Modules Arguments

The final part of the command is a single or space separated list of multiple modules to install. The module names should be the same ones used to import them in code e.g. adafruit_display_text.

Tab Completion

The modules argument supports tab completion while you're entering the modules into terminal. So if you type circup install ad then press the Tab key, it will autocomplete the rest of the word "adafruit_". If you press the Tab key again it will offer to show you all of the possible module names.

If you press the y key it will output a list of module names that match the partial entry currently at the end of the command. Depending on the length of the partial module that is currently entered it could be a rather long list. As you get more of the partial module name entered it will narrow down the list of valid module names. 

If there is only a single possible valid module name it will autocomplete the full name.

Example Usage

Here are a few example usages of the install command:

Example Output

The circup uninstall command is used to uninstall the specified module(s) from the connected device.

The uninstall command does not have any other specific options beyond the --help argument which prints the built-in documentation info.

Modules Arguments

The final part of the command is a single or space separated list of multiple modules to uninstall. The module names should be the same ones used to import them in code e.g. adafruit_display_text.

Example Usage:

Example Output

The circup update command will check all of the libraries on the connected device and prompt the user to install new versions of any that are out of date.

Options Details

As usual the --help argument will print out the built-in documentation information about the command.

The only other option for the update command is the --all argument which will install the new versions of each library without prompting individually for each one.

Example Usage

Example Output

The circup list command will print a list of all libraries found on the connected device along with whether or not the are up to date. 

The only argument that the list command supports is --help which prints out the built-in documentation information.

Example Usage

Example Output

The circup freeze command will output the current libraries installed on the connected device. It outputs each library and the current version loaded.

This is helpful for sharing a list of a requirements for your project to another person or another device.

Options Details

The --help flag will print out the built-in documentation information.

The -r, or --requirement flag will cause the output to be written into a requirements.txt file instead of being printed to the terminal.

Example Usage

Example Output

The circup example command can be used to load the example scripts from any library in a bundle onto the connected device.

Options Details

There are only 2 options available for the example command. --help which prints the built-in documentation information.

The --overwrite option will direct the command to overwrite the existing copy of the example script on the device if one exists. Without this flag the command will output an error if it finds an existing example already on the device. If you modify example scripts be careful to backup any modified copies of examples on your device if you do use the --overwrite command.

Examples Arguments

The final part of the command is a single or space separated list of examples to copy to the connected device. The examples must be in the form of lib_shortname/example_name e.g. neopixel/neopixel_simpletest or logging/logging_simpletest.

Tab Completion

The examples argument supports tab completion to autocomplete valid library and example names. So if you enter a partial library short name it will either autocomplete fully if there is only a single valid match, or autocomplete as much as it can if there are multiple possible matches based on the partial entry.

If you press the [Tab] key twice it will print out the list of possible matches based upon the current partial value entered.

Example Usage

Example Output

The circup show command will print a list of all libraries that are available in any bundles that circup is aware of. 

The list is rather long, 487 libraries at the time of this writing, so be prepared to do some scrolling if you're trying to find something specific within it. The optional MATCH argument can be used to narrow the list to libraries of interest by searching for a specific string.

Options Details

The --help flag will print out the built-in documentation information.

Match Argument

The match argument is optional. If passed the list will be narrowed down to only libraries that include the string specified. This can be used to help find libraries you are interested in by searching for keywords like circup show ble to find libraries related to BLE for example.

Example Usage

Example Output

The remaining commands all pertain managing the bundles on your local system that circup will look for libraries inside of. By default circup uses these 3 bundles:

• Adafruit Library Bundle
• Community Library Bundle
• CircuitPython Org Bundle

These commands allow you to add and remove other 3rd party bundles if you'd like. Once added then circup will be able to install libraries from those 3rd party bundles.

If you don't want to use any 3rd party bundles then you won't need to use these commands. 

Bundle Show Command

The circup bundle-show command will print a list of the currently tracked bundles, and information about the current versions.

Options Details

The --help argument will print the built-in documentation information.

The --modules argument will print the list of libraries within each bundle in additional to the bundle information. This is similar to the output from the circup show command, but the libraries are grouped by which bundle their in and split up. 

Example Usage

Example Output

Bundle Add Command

The circup bundle-add command will add a new bundle to be tracked by circup. 

One such possible bundle is the CircuitPython Fonts Bundle. It contains several sizes of different open source fonts formatted to work with Circuitpython displayio.

You only need to run this command once to add a bundle. After it comples circup will track the added bundle and download new versions to your computer when they're available. You will also be able to install libraries from the added bundle.

Options Details

The only optional argument is the --help flag which prints the built-in documentation information. 

The final part of the command is the Bundle argument, it is required and must be in the format of a user/repository string pointing to a valid library bundle hosted on Github.

Example Usage

Example Output

Bundle Remove Command

The circup bundle-remove command is the opposite of the bundle-add command. circup bundle-remove will remove the specified bundle from your computer and circup will stop tracking it. After removal you will not be able to install the libraries from that bundle any longer.

Options Details

The --help argument will print out the built-in documentation information. 

The --reset argument will remove all non-default bundles that have been previously added. 

Bundle Argument

If you do not use the --reset argument, then the final part of this command is the Bundle argument. Just as with bundle-add the value must be in the format of a user/repository string. If you're unsure about the correct names to use then run the circup bundle-show command to see the bundles that are installed and then choose the one that you want to install and copy the name printed out.

Example Usage

Example Output