circup

Interactively update modules on a device

$ circup update

$ circup install [library_name]

$ circup show [partial_name]

$ circup freeze

$ circup freeze [[-r|--requirement]]

circup [global_options] command [arguments]

Common Usage Examples:
circup install adafruit_motor
circup update
circup list
circup --path /media/CIRCUITPY install adafruit_displayio

command
    The specific action to perform. See subcommands below for details.

install <library>
    Installs the specified CircuitPython library (or libraries, space-separated) onto the connected device. Can also accept `requirements.txt` style input via `--input-requirements`.

uninstall <library>
    Removes the specified CircuitPython library (or libraries, space-separated) from the connected device.

update [<library>]
    Updates all installed CircuitPython libraries to their latest compatible versions. If a library name is specified, only that library will be updated.

list
    Lists all CircuitPython libraries currently installed on the connected device.

freeze
    Lists installed CircuitPython libraries and their versions, along with compatible libraries from the current bundle, similar to `pip freeze`.

search <query>
    Searches for CircuitPython libraries matching the specified query in the available bundles.

show <library>
    Displays detailed information about a specific CircuitPython library.

bundle
    Displays information about the current CircuitPython library bundle being used by circup.

-h, --help
    Displays a help message and exits. Can be used globally or with subcommands (e.g., `circup install --help`).

-v, --version
    Displays the program's version number and exits.

--path <path>
    Specifies the mount point of the CircuitPython device (e.g., /media/CIRCUITPY) if auto-detection fails.

--target-board <board_name>
    Specifies the target board name (e.g., `feather_m4_express`) to ensure library compatibility.

--input-requirements <file>
    Reads a newline-separated list of library names from the specified file to install or update.

--output-requirements <file>
    Writes a list of currently installed libraries to the specified file, similar to a `pip` requirements file.

--auto-update
    Automatically updates circup itself to the latest version before running the requested command.

--skip-version-check
    Skips checking if the circup tool itself is out of date.

--json
    Outputs command results in JSON format, useful for scripting or parsing.

--usb-device-id <id>
    Connects to a specific USB device ID, useful when multiple CircuitPython boards are connected.

--pretend
    Performs a dry run, showing what changes would be made without actually modifying the device.

circup is a specialized command-line utility built with Python, designed for efficient management of libraries on CircuitPython-enabled microcontroller boards. These boards include popular options like Adafruit Feathers, ESP32s, and Raspberry Pi Picos.

The primary function of circup is to simplify the process of installing, updating, uninstalling, and listing CircuitPython libraries directly on the connected device's `CIRCUITPY` drive. It acts as a bridge between the host computer and the microcontroller, ensuring that the necessary libraries are available and up-to-date for your embedded projects.

It can fetch libraries from the official CircuitPython library bundle, specified URLs, or local paths. This tool is indispensable for developers working with CircuitPython, helping to manage dependencies, ensure compatibility, and streamline the development workflow by providing a robust and easy-to-use interface for library management.

circup is not a core Linux utility but a Python application. It requires Python and `pip` to be installed on the host system. It also relies on a CircuitPython device being connected via USB and properly mounted as a mass storage device (typically named `CIRCUITPY`). Permissions issues, particularly with USB device access (e.g., `udev` rules on Linux), can prevent circup from functioning correctly. An active internet connection is usually required to download libraries from the CircuitPython bundle.

To use circup, you must first install it on your host system using pip, Python's package installer:
pip install circup
It's recommended to install it within a Python virtual environment to avoid conflicts with system-wide packages.

circup is an integral part of the larger CircuitPython ecosystem, a Python implementation for microcontrollers. It exclusively manages libraries specifically designed for CircuitPython, which are often optimized for low-memory environments and hardware interaction.

circup was developed by Adafruit Industries as an essential tool for their CircuitPython ecosystem. Its inception aimed to streamline the often cumbersome process of managing external libraries on memory-constrained microcontroller devices. Since its initial release, it has undergone continuous development, with regular updates and improvements, making it a robust and widely used utility within the CircuitPython community. It's maintained as an open-source project on GitHub.

pip(1), mount(8), lsusb(8), python(1)