Installing Charmcraft

How to install


The recommended way to install charmcraft is from the stable channel with

sudo snap install charmcraft --classic

There are multiple channels other than stable. See the full list with
snap info charmcraft.

We recommend either latest/stable or latest/candidate for everyday charming. With the snap you will always be up to date as Charmhub services and APIs evolve. Charmcraft supports Kubernetes operator development.

On Linux, Charmcraft currently depends on LXD to build the charms in a container matching the target base(s). Charmcraft will offer to install LXD if required, but here are steps to set it up manually:

$ sudo snap install lxd
$ sudo adduser $USER lxd
$ newgrp lxd
$ lxd init --auto


Charmcraft does not yet support Mac OS.


Charmcraft does not yet support Windows.

Developer Mode (Unsupported)

Use pip to install Charmcraft for development purposes. Using a virtualenv is strongly recommended. For example:

git clone
cd charmcraft
python3 -m venv venv
source venv/bin/activate
pip install -e .[dev]

Then run Charmcraft with CHARMCRAFT_DEVELOPER=y to enable developer-mode. For example:

CHARMCRAFT_DEVELOPER=y charmcraft pack


CHARMCRAFT_DEVELOPER=y python3 -m charmcraft pack

NOTE: this is not supported for production use and may cause unexpected behaviors.

Using Charmcraft

Charmcraft enables collaboration between charmed operator developers, and
publication on Charmhub, home of the Charmed Operator

Use charmcraft to:

  • Init a new charmed operator file structure
  • Build your operator into a charmed operator for distribution
  • Register your charmed operator name on Charmhub
  • Upload your charmed operators to Charmhub
  • Release your charmed operators into channels

You can use charmcraft with operators written in any language but we
recommend the Python Operator Framework on
which is also on
for ease of development and

Charmcraft and the Charmed Operator Framework extend the operator pattern
beyond Kubernetes with universal
that drive Linux and
Windows apps. The universal operator pattern is very exciting for
multi-cloud application management.

Initialize a charm operator package file structure

Use charmcraft init to create a new template charm operator file tree:

$ mkdir my-new-charm; cd my-new-charm
$ charmcraft init
Charm operator package file and directory tree initialized.
TODO: Describe your charm in a few paragraphs of Markdown Provide high-level usage, such as required config or relations
   actions.yaml: change this example to suit your needs.
    config.yaml: change this example to suit your needs.
  metadata.yaml: fill out the charm's description
  metadata.yaml: fill out the charm's summary
  metadata.yaml: replace with containers for your workload (delete for non-k8s)
  metadata.yaml: each container defined above must specify an oci-image resource
   src/ change this example to suit your needs.
   src/ change this example to suit your needs.
   src/ change this example to suit your needs.

You will now have all the essential files for a charmed operator, including
the actual src/ skeleton and various items of metadata. Charmcraft
assumes you want to work in Python so it will add requirements.txt with
the Python operator framework ops, and other conventional development
support files.

Build your charm

With a correct metadata.yaml and with ops in requirements.txt you can
build a charmed operator with:

$ charmcraft build
Created 'test-charm.charm'.

charmcraft build will fetch additional files into the tree from PyPI based
on requirements.txt and will compile modules using a virtualenv.

The charmed operator is just a zipfile with metadata and the operator code

$ unzip -l test-charm.charm
Archive:  test-charm.charm
  Length      Date    Time    Name
---------  ---------- -----   ----
      221  2020-11-15 08:10   metadata.yaml
    25304  2020-11-15 08:14   venv/yaml/__pycache__/scanner.cpython-38.pyc
---------                     -------
   812617                     84 files

Now, if you have a Kubernetes cluster with the Juju OLM accessible you can issue
juju deploy ./my-new-charm.charm --resource httpbin-image=kennethreitz/httpbin.
You do not need to publish your operator on Charmhub, you can pass the charmed
operator file around directly to users, or for CI/CD purposes.

Advanced Usage

Specifying a Charmcraft Snap Channel to use in Managed Environment

When instantiating a build environment (LXD or Multipass), Charmcraft will install the Charmcraft snap found on the host in the target environment. This ensures that the version running in the managed environment is synchronized with the host version. For cases where the snap is not being used on the host, Charmcraft will install from from the stable channel in the Snap Store. This may be overridden with environment variable CHARMCRAFT_INSTALL_SNAP_CHANNEL=<channel>.

For example, CHARMCRAFT_INSTALL_SNAP_CHANNEL=latest/edge charmcraft pack will pack the charm(s) using Charmcraft from the latest/edge channel in any instantiated build environments.

Last updated a month ago.