How to find and use a charm library
This documents shows how to take advantage of existing charm libraries.
You’ve come to the conclusion that you’d like a charm library. The first thing to do is check if there is already an existing one that you can use. For example, if the charm you’re writing needs to interact with another service, you should check if that service provides any library that would help in that interaction.
The easiest way to find an existing library for a given charm is via
charmcraft list-lib, as shown below. This will query Charmhub and show which libraries are published for the specified charm, along with API/patch versions.
jdoe@machine:/home/jane/autoblog$ charmcraft list-lib blogsystem Library name API Patch superlib 1 0
The listing will not show older API versions; this ensures that new users always start with the latest version.
Another good way to search for libraries is to explore the charm collection on Charmhub.
You’ve found a library that suits you. Now, you need to fetch it. To do this,
charmcraft fetch-lib followed by the full library path:
$ charmcraft fetch-lib charms.demo.v0.demo Library charms.demo.v0.demo version 0.1 downloaded.
Charm libraries are always located according to the pattern:
$CHARMDIR/lib/charms/<charm_name>/v<API>/<library_name>.py. See The location of a charm library inside a charm.
This command will download the library, creating the required directory layout in your charm directory:
$ ls -l lib/charms/demo/v0/demo.py -rw-rw-r-- 1 user user 1061 Apr 06 15:24 lib/charms/demo/v0/demo.py
This file is now part of your charm’s project. It will be packed inside your charm and distributed with it when the charm is packaged and published with
You’ve fetched a library—it’s now time to use it! To use the library, you need to import it in your charm’s code, as shown below. (Note that the charm automatically has the
lib directory as part of the Python import paths.)
from charms.demo.v0 import demo
To update the version of the library you are consuming, run the
charmcraft fetch-lib command again—if there is an update available, this will fetch it:
$ charmcraft fetch-lib charms.demo.v0.demo Library charms.demo.v0.demo was already up to date in version 0.1.
Last updated 5 months ago.