How to set up a charm project

To set up a charm project for a machine / Kubernetes charm, create a directory for your charm project and inside of it run the charmcraft init command with the --profile flag followed by the argument machine / kubernetes. For example, to initialise a machine charm:

charmcraft init --profile machine

This will produce all the basic directory structure and files that you will need for your charm, including all basic content, according to the latest charming standards (regarding Charmcraft, Ops, Tox, etc.).

Expand to view a sample session
# Create the charm directory:
~/$ mkdir my-machine-charm

# Enter the charm directory:
~/my-machine-charm$ cd my-machine-charm/

# Initialise the tree structure for a machine charm:
~/my-machine-charm$ charmcraft init --profile machine
Charmed operator package file and directory tree initialised.                                                                                                                                
Now edit the following package files to provide fundamental charm metadata                                                                                                                   
and other information:                                                                                                                                                                       
# Inspect the generated tree structure:                                                                                        
~/my-machine-charm$ ls -R
.:  LICENSE  charmcraft.yaml  pyproject.toml  requirements.txt  src  tests  tox.ini


integration  unit



# Inspect the prepopulated content templates. E.g., for 'charmcraft.yaml':
~/my-machine-charm$ cat charmcraft.yaml 
# This file configures Charmcraft.
# See for guidance.

# (Required)
name: my-machine-charm

# (Required)
type: charm

# (Recommended)
title: Charm Template

# (Required)
summary: A very short one-line summary of the charm.

# (Required)
description: |
  A single sentence that says what the charm is, concisely and memorably.

  A paragraph of one to three short sentences, that describe what the charm does.

  A third paragraph that explains what need the charm meets.

  Finally, a paragraph that describes whom the charm is useful for.

# (Required for 'charm' type)
  - build-on:
    - name: ubuntu
      channel: "22.04"
    - name: ubuntu
      channel: "22.04"

The command also allows you to not specify any profile (in that case you get the simple profile – a Kubernetes profile with lots of scaffolding, suitable for beginners) and has flags that you can use to specify a different directory to operate in, a charm name different from the name of the root directory, etc.

See more: charmcraft init, List of files in the charm project

Contributors: @mmkay

Last updated a month ago. Help improve this document in the forum.