# Use circup to easily keep your CircuitPython libraries up to date ## Overview 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](https://github.com/ntoll). ![](https://cdn-learn.adafruit.com/assets/assets/000/081/042/medium800/customer___partner_projects_guide_main.jpg?1568756034) 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. ### Adafruit Grand Central M4 Express featuring the SAMD51 [Adafruit Grand Central M4 Express featuring the SAMD51](https://www.adafruit.com/product/4064) Are you ready? Really ready? Cause here comes the **Adafruit Grand Central** featuring the **Microchip ATSAMD51**. This dev board is so big, it's not named after a Metro train, it's a whole freakin' _station_! This board is like a freight... In Stock [Buy Now](https://www.adafruit.com/product/4064) [Related Guides to the Product](https://learn.adafruit.com/products/4064/guides) ![Angled Shot of the Adafruit Grand Central M4 Express featuring the SAMD51.](https://cdn-shop.adafruit.com/640x480/4064-05.jpg) The PyPortal is packed with so many features, that it uses a lot of libraries, making this tool especially useful. ### Adafruit PyPortal - CircuitPython Powered Internet Display [Adafruit PyPortal - CircuitPython Powered Internet Display](https://www.adafruit.com/product/4116) **PyPortal** , our easy-to-use IoT device that allows you to create all the things for the “Internet of Things” in minutes. Make custom touch screen interface GUIs, all open-source, and Python-powered using tinyJSON / APIs to get news, stock, weather, cat photos,... Out of Stock [Buy Now](https://www.adafruit.com/product/4116) [Related Guides to the Product](https://learn.adafruit.com/products/4116/guides) ![Front view of a Adafruit PyPortal - CircuitPython Powered Internet Display with a pyportal logo image on the display. ](https://cdn-shop.adafruit.com/640x480/4116-00.jpeg) Our PyGamer and PyBadge also use quite a few libraries. ### Adafruit PyGamer for MakeCode Arcade, CircuitPython or Arduino [Adafruit PyGamer for MakeCode Arcade, CircuitPython or Arduino](https://www.adafruit.com/product/4242) What fits in your pocket, is fully Open Source, and can run CircuitPython, MakeCode Arcade or Arduino games you write yourself? That's right, it's the **Adafruit PyGamer!** We wanted to make an entry-level gaming handheld for DIY gaming, and maybe a little... Out of Stock [Buy Now](https://www.adafruit.com/product/4242) [Related Guides to the Product](https://learn.adafruit.com/products/4242/guides) ![Angled shot of Adafruit PyGamer for MakeCode Arcade, CircuitPython or Arduino.](https://cdn-shop.adafruit.com/640x480/4242-00.jpg) ### Adafruit PyBadge for MakeCode Arcade, CircuitPython, or Arduino [Adafruit PyBadge for MakeCode Arcade, CircuitPython, or Arduino](https://www.adafruit.com/product/4200) What's the size of a credit card and can run CircuitPython, MakeCode Arcade or Arduino? That's right, its the **Adafruit PyBadge!** We wanted to see how much we could cram into a ​3 3⁄8 × ​2 1⁄8 inch rounded rectangle, to make an all-in-one dev board with... Out of Stock [Buy Now](https://www.adafruit.com/product/4200) [Related Guides to the Product](https://learn.adafruit.com/products/4200/guides) ![Angled shot of a Adafruit PyBadge for MakeCode Arcade, CircuitPython, or Arduino. ](https://cdn-shop.adafruit.com/640x480/4200-01.jpg) Another very popular option is the Adafruit Feather M4 Express. ### Adafruit Feather M4 Express - Featuring ATSAMD51 [Adafruit Feather M4 Express - Featuring ATSAMD51](https://www.adafruit.com/product/3857) It's what you've been waiting for, the Feather M4 Express featuring ATSAMD51. This Feather is fast like a swift, smart like an owl, strong like a ox-bird (it's half ox, half bird, OK?) This feather is powered by our new favorite chip, the **ATSAMD51J19** -  with... In Stock [Buy Now](https://www.adafruit.com/product/3857) [Related Guides to the Product](https://learn.adafruit.com/products/3857/guides) ![Angled shot of a Adafruit Feather M4 Express. ](https://cdn-shop.adafruit.com/640x480/3857-10.jpg) If you would like something in between, you can go with the Adafruit Metro M4 Express. ### Adafruit Metro M4 feat. Microchip ATSAMD51 [Adafruit Metro M4 feat. Microchip ATSAMD51](https://www.adafruit.com/product/3382) Are you ready? Really ready? Cause here comes the fastest, most powerful Metro ever. The **Adafruit Metro M4** featuring the **Microchip ATSAMD51**. This Metro is like a bullet train, with its 120MHz Cortex M4 with floating point support. Your code will zig and zag... In Stock [Buy Now](https://www.adafruit.com/product/3382) [Related Guides to the Product](https://learn.adafruit.com/products/3382/guides) ![Angled shot of a Adafruit Metro M4 feat. Microchip ATSAMD51. ](https://cdn-shop.adafruit.com/640x480/3382-13.jpg) If you need a Metro M4 that can also do WiFi, you may like the Adafruit Metro M4 Express Airlift Lite. ### Adafruit Metro M4 Express AirLift (WiFi) - Lite [Adafruit Metro M4 Express AirLift (WiFi) - Lite](https://www.adafruit.com/product/4000) Give your next project a lift with _AirLift_ - our witty name for the ESP32 co-processor that graces this Metro M4. You already know about the  **Adafruit Metro M4**  featuring the  **Microchip ATSAMD51** , with it's 120MHz Cortex M4 with... In Stock [Buy Now](https://www.adafruit.com/product/4000) [Related Guides to the Product](https://learn.adafruit.com/products/4000/guides) ![Adafruit Metro M4 Airlift Lite dev board with SAMD51 an ESP32 Wifi Co-processor.](https://cdn-shop.adafruit.com/640x480/4000-08.jpg) # Use circup to easily keep your CircuitPython libraries up to date ## Prepare for Install Info: ## 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. ![](https://cdn-learn.adafruit.com/assets/assets/000/081/052/medium800/customer___partner_projects_python_windows_store.png?1568760889) 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. ![](https://cdn-learn.adafruit.com/assets/assets/000/081/055/medium800/customer___partner_projects_environment_settings.png?1568761113) 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. Info: If you have Python 3.9 or later on macOS, you don't need to install a newer version of Python. ## 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**. ![](https://cdn-learn.adafruit.com/assets/assets/000/081/049/medium800/customer___partner_projects_requirements_check.png?1568759851) 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`. ![](https://cdn-learn.adafruit.com/assets/assets/000/081/048/medium800/customer___partner_projects_pip3_upgrade.png?1568759692) 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.  ```terminal sudo apt install python3-venv python3 -m venv env source env/bin/activate ``` # Use circup to easily keep your CircuitPython libraries up to date ## Install CircUp Info: 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: ```terminal pip install setuptools pip install circup ``` Warning: ![](https://cdn-learn.adafruit.com/assets/assets/000/083/224/medium800/customer___partner_projects_pypi-install.png?1572382410) 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. ![](https://cdn-learn.adafruit.com/assets/assets/000/083/225/medium800/customer___partner_projects_version.png?1572382537) ## 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: ```terminal pip install --upgrade circup ``` # Use circup to easily keep your CircuitPython libraries up to date ## Usage ## 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](https://github.com/adafruit/circup) 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](https://learn.adafruit.com/keep-your-circuitpython-libraries-on-devices-up-to-date-with-circup/install-command "Install Command") - Install a named module(s) onto the device. - [uninstall](https://learn.adafruit.com/keep-your-circuitpython-libraries-on-devices-up-to-date-with-circup/uninstall-command "Uninstall Command") - Uninstall a named module(s) from the connected device. - [update](https://learn.adafruit.com/keep-your-circuitpython-libraries-on-devices-up-to-date-with-circup/update-command "Update Command") - Update modules on the device. - [list](https://learn.adafruit.com/keep-your-circuitpython-libraries-on-devices-up-to-date-with-circup/list-command "List Command") - Lists all out of date modules found on the connected device. - [freeze](https://learn.adafruit.com/keep-your-circuitpython-libraries-on-devices-up-to-date-with-circup/freeze-command "Freeze Command") - Output details of all the modules found on the connected. - [example](https://learn.adafruit.com/keep-your-circuitpython-libraries-on-devices-up-to-date-with-circup/example-command) - Copy named example(s) from a bundle onto the device. - [show](https://learn.adafruit.com/keep-your-circuitpython-libraries-on-devices-up-to-date-with-circup/show-command "Show Command") - Show a list of available modules in the bundle. - [bundle-add, bundle-remove, bundle-show](https://learn.adafruit.com/keep-your-circuitpython-libraries-on-devices-up-to-date-with-circup/bundle-commands "Bundle Commands") - Manage local bundles. Info: Circup supports both PY and MPY library files. ## 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):** ```terminal $ circup --host 192.168.1.188 --password Passw0rd install adafruit_display_text $ circup --verbose install adafruit_display_text $ circup --path my_project/ --cpy-version 9.0.0 install adafruit_display_text ``` **Incorrect Examples (Arguments After Command):** Danger: These are intended to illustrate what NOT to do. ```terminal $ circup install adafruit_display_text --host 192.168.1.188 --password Passw0rd $ circup install adafruit_display_text --path my_project/ --cpy-version 9.0.0 $ circup install adafruit_display_text --verbose ``` ## 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. Warning: For Circup to work, you must enable the web workflow by putting WIFI credentials and a web workflow password into your settings.toml file. If your device supports USB Storage, then you also need to eject or disable the USB storage, or set the device storage to be writable for CircuitPython. See here for instructions: https://learn.adafruit.com/getting-started-with-web-workflow-using-the-code-editor/device-setup - `--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: ```terminal Auto locating USB Disk based device failed. Please specify --path argument or ensure your device is connected and mounted under the name CIRCUITPY. Could not find a connected CircuitPython device. ``` ### 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. # Use circup to easily keep your CircuitPython libraries up to date ## Install Command The `circup install` command is used to install the specified libraries onto the connected device. ```terminal $ circup install --help Usage: circup install [OPTIONS] [MODULES]... Install a named module(s) onto the device. Multiple modules can be installed at once by providing more than one module name, each separated by a space. Modules can be from a Bundle or local filepaths. Options: --py Install the .py version of the module(s) instead of the mpy version. -r, --requirement FILE specify a text file to install all modules listed in the text file. Typically requirements.txt. -a, --auto Install the modules imported in code.py. -U, --upgrade Upgrade modules that are already installed. --auto-file TEXT Specify the name of a file on the board to read for auto install. Also accepts an absolute path or a local ./ path. --help Show this message and exit. ``` ## 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. Warning: Tab Completion may not work on some systems such as the Raspberry Pi ```terminal $ circup install adafruit_[Tab] Display all 329 possibilities? (y or n) ``` 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.  ```terminal $ circup install adafruit_display[Tab] adafruit_display_notification adafruit_displayio_sh1106 adafruit_display_shapes adafruit_displayio_sh1107 adafruit_display_text adafruit_displayio_ssd1305 adafruit_displayio_flipclock adafruit_displayio_ssd1306 adafruit_displayio_layout ``` If there is only a single possible valid module name it will autocomplete the full name. ```terminal $ circup install adafruit_lo[Tab] $ circup install adafruit_logging ``` ## Example Usage Here are a few example usages of the install command: ```terminal $ circup install adafruit_rsa $ circup install adafruit_display_shapes adafruit_display_text $ circup install adafruit_logging --py --upgrade $ circup --path cool_project/ --cpy-version 9.0.0 install adafruit_logging $ circup --host 192.168.1.188 --password Passw0rd install adafruit_display_text $ circup --host 192.168.1.188 --password Passw0rd install --auto ``` ## Example Output ```terminal $ circup install adafruit_rsa Found device at /media/myusername/CIRCUITPY, running CircuitPython 8.2.9. A newer version of CircuitPython (9.0.5) is available. Get it here: https://circuitpython.org/board/adafruit_feather_esp32s3_tft Downloading latest bundles for adafruit/Adafruit_CircuitPython_Bundle (20240525). py: Extracting: [####################################] 100% 8.x-mpy: Extracting: [####################################] 100% 9.x-mpy: Extracting: [####################################] 100% OK Downloading latest bundles for adafruit/CircuitPython_Community_Bundle (20240524). py: Extracting: [####################################] 100% 8.x-mpy: Extracting: [####################################] 100% 9.x-mpy: Extracting: [####################################] 100% OK Searching for dependencies for: ['adafruit_rsa'] Ready to install: ['adafruit_hashlib', 'adafruit_logging', 'adafruit_rsa'] 'adafruit_hashlib' is already installed. 'adafruit_logging' is already installed. Installed 'adafruit_rsa'. ``` ```terminal circup --host 192.168.1.111 --password Passw0rd install adafruit_display_text Found device at http://:Passw0rd@192.168.1.111, running CircuitPython 9.0.5. Searching for dependencies for: ['adafruit_display_text'] Ready to install: ['adafruit_bitmap_font', 'adafruit_display_text'] 'adafruit_bitmap_font' is already installed. Installed 'adafruit_display_text'. ``` # Use circup to easily keep your CircuitPython libraries up to date ## Uninstall Command The `circup uninstall` command is used to uninstall the specified module(s) from the connected device. ```terminal $ circup uninstall --help Usage: circup uninstall [OPTIONS] [MODULE]... Uninstall a named module(s) from the connected device. Multiple modules can be uninstalled at once by providing more than one module name, each separated by a space. Options: --help Show this message and exit. ``` 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: ```terminal $ circup uninstall adafruit_rsa $ circup uninstall adafruit_display_shapes adafruit_display_text $ circup uninstall adafruit_logging --py --upgrade $ circup --path cool_project/ --cpy-version 9.0.0 uninstall adafruit_logging $ circup --host 192.168.1.188 --password Passw0rd uninstall adafruit_display_text ``` ## Example Output ```terminal circup uninstall adafruit_rsa Found device at /media/myusername/CIRCUITPY, running CircuitPython 9.0.5. Uninstalling ('adafruit_rsa',) from /media/myusername/CIRCUITPY Uninstalled 'adafruit_rsa'. ``` # Use circup to easily keep your CircuitPython libraries up to date ## Update Command 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. ```terminal $ circup update --help Usage: circup update [OPTIONS] Checks for out-of-date modules on the connected CIRCUITPYTHON device, and prompts the user to confirm updating such modules. Options: --all Update all modules without Major Version warnings. --help Show this message and exit. ``` ## 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 ```terminal $ circup update $ circup update --all $ circup --host 192.168.1.188 --password Passw0rd update $ circup --path mock_device/ update ``` ## Example Output ```terminal $ circup update Found device at /media/myusername/CIRCUITPY, running CircuitPython 9.0.0-alpha.4. A newer version of CircuitPython (9.0.5) is available. Get it here: https://circuitpython.org/board/adafruit_funhouse Found 1 module[s] needing update. Please indicate which module[s] you wish to update: Update 'adafruit_rsa'? [y/N]: y Updated adafruit_rsa Checking 1 updated module[s] for missing requirements. Ready to install: ['adafruit_hashlib', 'adafruit_logging'] Installed 'adafruit_hashlib'. Installed 'adafruit_logging'. ``` # Use circup to easily keep your CircuitPython libraries up to date ## List Command 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.  ```terminal $ circup list --help Auto locating USB Disk based device failed. Please specify --path argument or ensure your device is connected and mounted under the name CIRCUITPY. Usage: circup list [OPTIONS] Lists all out of date modules found on the connected CIRCUITPYTHON device. Options: --help Show this message and exit. ``` The only argument that the list command supports is `--help` which prints out the built-in documentation information. ## Example Usage ```terminal $ circup list $ circup --host 192.168.1.188 --password Passw0rd list $ circup --path mock_device/ list ``` ## Example Output ```terminal $ circup list Found device at /media/myusername/CIRCUITPY, running CircuitPython 9.0.5. The following modules are out of date or probably need an update. Major Updates may include breaking changes. Review before updating. MPY Format changes from Circuitpython 8 to 9 require an update. Module Version Latest Update Reason ---------------------------- ------------- ------- -------------- adafruit_connection_manager 1.0.1 3.1.0 Major Version adafruit_ntp 3.0.13 3.1.1 Minor Version adafruit_bme680 3.7.4 3.7.5 Minor Version adafruit_bitmap_font 2.0.2 2.1.1 MPY Format adafruit_minimqtt 7.6.3 7.9.0 Minor Version adafruit_httpserver 4.5.6 4.5.8 Minor Version adafruit_bus_device 5.2.8 5.2.9 Minor Version adafruit_wiznet5k 5.0.9 7.1.1 Major Version adafruit_display_shapes 2.8.2 2.8.3 Minor Version adafruit_itertools 2.1.0 2.1.1 Minor Version ``` # Use circup to easily keep your CircuitPython libraries up to date ## Freeze Command 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. ```terminal $ circup freeze --help Usage: circup freeze [OPTIONS] Output details of all the modules found on the connected CIRCUITPYTHON device. Option -r saves output to requirements.txt file Options: -r, --requirement --help Show this message and exit. ``` ## 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 ```terminal $ circup freeze $ circup freeze -r $ circup freeze --requirement $ circup --host 192.168.1.188 --password Passw0rd freeze $ circup --path mock_device/ freeze $ circup --path cool_project/ --cpy-version 9.0.0 --board-id pygamer freeze ``` ## Example Output ```terminal $ circup freeze Found device at /media/myusername/CIRCUITPY, running CircuitPython 9.0.5. adafruit_connection_manager==1.0.1 adafruit_ntp==3.0.13 adafruit_datetime==1.2.7 adafruit_debouncer==2.0.8 adafruit_ticks==1.0.13 adafruit_wave==0.0.3 adafruit_bme680==3.7.4 adafruit_bitmap_font==2.0.2 adafruit_display_text==3.1.0 adafruit_minimqtt==7.6.3 adafruit_io==5.8.2 adafruit_httpserver==4.5.6 adafruit_bus_device==5.2.8 asyncio==1.3.1 adafruit_imageload==1.20.2 adafruit_register==1.9.18 ``` # Use circup to easily keep your CircuitPython libraries up to date ## Example Command The `circup example` command can be used to load the example scripts from any library in a bundle onto the connected device. ```terminal $ circup example --help Usage: circup example [OPTIONS] EXAMPLES... Copy named example(s) from a bundle onto the device. Multiple examples can be installed at once by providing more than one example name, each separated by a space. Options: --overwrite Overwrite the file if it exists. --help Show this message and exit. ``` ## 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. ```terminal $ circup example req[Tab] # auto completes to: $ circup example requests/ $ circup example neopixel/neopixel_s[Tab] # auto completes to: $ circup example neopixel/neopixel_simpletest ``` If you press the [Tab] key twice it will print out the list of possible matches based upon the current partial value entered. ```terminal $ circup example neopixel/[Tab] # auto completes to: $ circup example neopixel/neopixel_ # press [Tab] twice more neopixel/neopixel_pixel neopixel/neopixel_rpi_simpletest neopixel/neopixel_rainbowio_simpletest neopixel/neopixel_simpletest ``` ## Example Usage ```terminal $ circup example neopixel/neopixel_simpletest $ circup --host 192.168.1.188 --password Passw0rd example display-shapes/display_shapes_simpletest $ circup example display-shapes/display_shapes_simpletest display-shapes/display_shapes_circle_animation ``` ## Example Output ```terminal $ circup example neopixel/neopixel_simpletest Found device at /media/myusername/CIRCUITPY, running CircuitPython 9.0.5. Copying: neopixel_simpletest.py ``` # Use circup to easily keep your CircuitPython libraries up to date ## Show Command 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. Info: Note that the show command does not interact with a connected device and therefore does not require a device to be connected in order to be used. ```terminal $ circup show --help Usage: circup show [OPTIONS] [MATCH] Show a list of available modules in the bundle. These are modules which *could* be installed on the device. If MATCH is specified only matching modules will be listed. Options: --help Show this message and exit. ``` ## 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 ```terminal $ circup show $ circup show ble $ circup show spark $ circup show display ``` ## Example Output ```terminal $ circup show AT24MAC_EEPROM P1AM absolute_mouse adafruit_24lc32 adafruit_74hc595 adafruit_acep7in # ... ``` ```terminal $ circup show ssd adafruit_displayio_ssd1305 adafruit_displayio_ssd1306 adafruit_ssd1305 adafruit_ssd1306 adafruit_ssd1322 adafruit_ssd1325 adafruit_ssd1327 adafruit_ssd1331 adafruit_ssd1351 adafruit_ssd1608 adafruit_ssd1675 adafruit_ssd1680 adafruit_ssd1681 13 shown of 487 packages. ``` # Use circup to easily keep your CircuitPython libraries up to date ## Bundle Commands 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. ```terminal $ circup bundle-show --help Usage: circup bundle-show [OPTIONS] Show the list of bundles, default and local, with URL, current version and latest version retrieved from the web. Options: --modules List all the modules per bundle. --help Show this message and exit. ``` ### 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 ```terminal $ circup bundle-show $ circup bundle-show --modules ``` ### Example Output ```terminal $ circup bundle-show adafruit/Adafruit_CircuitPython_Bundle https://github.com/adafruit/Adafruit_CircuitPython_Bundle version = 20240525 adafruit/CircuitPython_Community_Bundle https://github.com/adafruit/CircuitPython_Community_Bundle version = 20240524 circuitpython/CircuitPython_Org_Bundle https://github.com/circuitpython/CircuitPython_Org_Bundle version = 20231031.2 ``` ## 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](https://github.com/adafruit/circuitpython-fonts "CircuitPython Fonts Bundle Repository"). 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. ```terminal $ circup bundle-add --help Usage: circup bundle-add [OPTIONS] [BUNDLE]... Add bundles to the local bundles list, by "user/repo" github string. A series of tests to validate that the bundle exists and at least looks like a bundle are done before validating it. There might still be errors when the bundle is downloaded for the first time. Options: --help Show this message and exit. ``` ### 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 ```terminal $ circup bundle-add adafruit/circuitpython-fonts ``` ### Example Output ```terminal $ circup bundle-add adafruit/circuitpython-fonts Added adafruit/circuitpython-fonts https://github.com/adafruit/circuitpython-fonts ``` ## 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. ```terminal $ circup bundle-remove --help Usage: circup bundle-remove [OPTIONS] [BUNDLE]... Remove one or more bundles from the local bundles list. Options: --reset Remove all local bundles. --help Show this message and exit. ``` ### 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 ```terminal $ circup bundle-remove adafruit/circuitpython-fonts $ circup bundle-remove --reset ``` ### Example Output ```terminal $ circup bundle-remove adafruit/circuitpython-fonts Bundle adafruit/circuitpython-fonts Do you want to remove that bundle ? [y/N]: y Removing the bundle from the local list adafruit/circuitpython-fonts ``` ## Featured Products ### Adafruit Grand Central M4 Express featuring the SAMD51 [Adafruit Grand Central M4 Express featuring the SAMD51](https://www.adafruit.com/product/4064) Are you ready? Really ready? Cause here comes the **Adafruit Grand Central** featuring the **Microchip ATSAMD51**. This dev board is so big, it's not named after a Metro train, it's a whole freakin' _station_! This board is like a freight... In Stock [Buy Now](https://www.adafruit.com/product/4064) [Related Guides to the Product](https://learn.adafruit.com/products/4064/guides) ### Adafruit Grand Central M4 Express featuring SAMD51 [Adafruit Grand Central M4 Express featuring SAMD51](https://www.adafruit.com/product/4084) Are you ready? Really ready? Cause here comes the **Adafruit Grand Central** featuring the **Microchip ATSAMD51**. This dev board is so big, it's not named after a Metro train, it's a whole freakin' _station_! This board is like a freight... In Stock [Buy Now](https://www.adafruit.com/product/4084) [Related Guides to the Product](https://learn.adafruit.com/products/4084/guides) ### Adafruit PyPortal - CircuitPython Powered Internet Display [Adafruit PyPortal - CircuitPython Powered Internet Display](https://www.adafruit.com/product/4116) **PyPortal** , our easy-to-use IoT device that allows you to create all the things for the “Internet of Things” in minutes. Make custom touch screen interface GUIs, all open-source, and Python-powered using tinyJSON / APIs to get news, stock, weather, cat photos,... Out of Stock [Buy Now](https://www.adafruit.com/product/4116) [Related Guides to the Product](https://learn.adafruit.com/products/4116/guides) ### Adafruit PyGamer for MakeCode Arcade, CircuitPython or Arduino [Adafruit PyGamer for MakeCode Arcade, CircuitPython or Arduino](https://www.adafruit.com/product/4242) What fits in your pocket, is fully Open Source, and can run CircuitPython, MakeCode Arcade or Arduino games you write yourself? That's right, it's the **Adafruit PyGamer!** We wanted to make an entry-level gaming handheld for DIY gaming, and maybe a little... Out of Stock [Buy Now](https://www.adafruit.com/product/4242) [Related Guides to the Product](https://learn.adafruit.com/products/4242/guides) ### Adafruit PyBadge for MakeCode Arcade, CircuitPython, or Arduino [Adafruit PyBadge for MakeCode Arcade, CircuitPython, or Arduino](https://www.adafruit.com/product/4200) What's the size of a credit card and can run CircuitPython, MakeCode Arcade or Arduino? That's right, its the **Adafruit PyBadge!** We wanted to see how much we could cram into a ​3 3⁄8 × ​2 1⁄8 inch rounded rectangle, to make an all-in-one dev board with... Out of Stock [Buy Now](https://www.adafruit.com/product/4200) [Related Guides to the Product](https://learn.adafruit.com/products/4200/guides) ### Adafruit Feather M4 Express - Featuring ATSAMD51 [Adafruit Feather M4 Express - Featuring ATSAMD51](https://www.adafruit.com/product/3857) It's what you've been waiting for, the Feather M4 Express featuring ATSAMD51. This Feather is fast like a swift, smart like an owl, strong like a ox-bird (it's half ox, half bird, OK?) This feather is powered by our new favorite chip, the **ATSAMD51J19** -  with... In Stock [Buy Now](https://www.adafruit.com/product/3857) [Related Guides to the Product](https://learn.adafruit.com/products/3857/guides) ### Adafruit Metro M4 feat. Microchip ATSAMD51 [Adafruit Metro M4 feat. Microchip ATSAMD51](https://www.adafruit.com/product/3382) Are you ready? Really ready? Cause here comes the fastest, most powerful Metro ever. The **Adafruit Metro M4** featuring the **Microchip ATSAMD51**. This Metro is like a bullet train, with its 120MHz Cortex M4 with floating point support. Your code will zig and zag... In Stock [Buy Now](https://www.adafruit.com/product/3382) [Related Guides to the Product](https://learn.adafruit.com/products/3382/guides) ### Adafruit Metro M4 Express AirLift (WiFi) - Lite [Adafruit Metro M4 Express AirLift (WiFi) - Lite](https://www.adafruit.com/product/4000) Give your next project a lift with _AirLift_ - our witty name for the ESP32 co-processor that graces this Metro M4. You already know about the  **Adafruit Metro M4**  featuring the  **Microchip ATSAMD51** , with it's 120MHz Cortex M4 with... In Stock [Buy Now](https://www.adafruit.com/product/4000) [Related Guides to the Product](https://learn.adafruit.com/products/4000/guides) ## Related Guides - [Adafruit Metro M4 Express featuring ATSAMD51](https://learn.adafruit.com/adafruit-metro-m4-express-featuring-atsamd51.md) - [Adafruit Feather M4 Express](https://learn.adafruit.com/adafruit-feather-m4-express-atsamd51.md) - [Introducing the Adafruit Grand Central M4 Express](https://learn.adafruit.com/adafruit-grand-central.md) - [Adafruit PyPortal - IoT for CircuitPython](https://learn.adafruit.com/adafruit-pyportal.md) - [Adafruit Metro M4 Express AirLift (WiFi)](https://learn.adafruit.com/adafruit-metro-m4-express-airlift-wifi.md) - [Adafruit PyBadge and PyBadge LC](https://learn.adafruit.com/adafruit-pybadge.md) - [Introducing Adafruit PyGamer](https://learn.adafruit.com/adafruit-pygamer.md) - [Adafruit NeoPXL8 FeatherWing and Library](https://learn.adafruit.com/adafruit-neopxl8-featherwing-and-library.md) - [PyGamer Marble Labyrinth in MakeCode Arcade](https://learn.adafruit.com/pygamer-marble-labyrinth-in-makecode-arcade.md) - [TFT Spirit Board](https://learn.adafruit.com/tft-spirit-board.md) - [Which CircuitPython Board is Right for You?](https://learn.adafruit.com/choose-your-circuitpython-board.md) - [Visual Studio Code for Education... and CircuitPython](https://learn.adafruit.com/visual-studio-code-for-education-and-circuitpython.md) - [Adafruit AirLift Shield - ESP32 WiFi Co-Processor](https://learn.adafruit.com/adafruit-airlift-shield-esp32-wifi-co-processor.md) - [PyPortal Weather Station](https://learn.adafruit.com/pyportal-weather-station.md) - [Using Dashblock to Create Custom APIs for PyPortal](https://learn.adafruit.com/using-dashblock-to-create-custom-apis-for-pyportal.md) - [Melting Picture Frame for PyPortal IoT images](https://learn.adafruit.com/pyportal-art-display.md) - [Deco Two-Key Feather Macro Pad](https://learn.adafruit.com/deco-two-key-keypad-macropad-circuitpython-feather.md) - [Halloween Countdown Display Matrix](https://learn.adafruit.com/halloween-countdown-display-matrix.md) - [ePaper Maze Maker](https://learn.adafruit.com/epaper-maze-maker.md) - [PyPortal Word of the Day Display](https://learn.adafruit.com/pyportal-word-of-the-day-display.md) - [Zelda Master Sword](https://learn.adafruit.com/zelda-master-sword.md)