rockcraft.yaml¶

This reference describes the purpose, usage, and examples of all available keys in a rock’s project file, rockcraft.yaml.

Top-level keys¶

name¶

Type

str

Description

The name of the project. This is used when uploading, publishing, or installing.

The project name must consist only of lower-case ASCII letters (a-z), numerals (0-9), and hyphens (-). It must contain at least one letter, not start or end with a hyphen, and not contain two consecutive hyphens. The maximum length is 40 characters.

Examples

name: ubuntu

name: jupyterlab-desktop

name: lxd

name: digikam

name: kafka

name: mysql-router-k8s

title¶

Type

str

Description

A human-readable title.

Examples

title: Ubuntu Linux

title: Jupyter Lab Desktop

title: LXD

title: DigiKam

title: Apache Kafka

title: MySQL Router K8s charm

summary¶

Type

str

Description

A short, single line description of the rock.

description¶

Type

str

Description

A full description of the rock, potentially including multiple paragraphs.

The description should say in full what the rock is for and who may find it useful.

version¶

Type

str

Description

The version of the project, enclosed in quotation marks.

Examples

version: '0.1'

version: 1.0.0

version: v1.0.0

version: '24.04'

base¶

Type

One of: ['bare', 'ubuntu@20.04', 'ubuntu@22.04', 'ubuntu@24.04', 'ubuntu@25.10', 'ubuntu@26.04']

Description

The base system image that the rock’s contents will be layered on.

This system is mounted and made available when using overlays. The special value bare means that the rock will have no base system, which is typically used with static binaries or Chisel slices.

build-base¶

Type

One of: ['ubuntu@20.04', 'ubuntu@22.04', 'ubuntu@24.04', 'ubuntu@25.10', 'devel']

Description

The system and version that will be used during the rock’s build, but not included in the final rock itself.

The build base comprises the set of tools and libraries that Rockcraft uses when building the rock’s contents.

This key is mandatory if base is bare. Otherwise, it is optional and defaults to the value of base.

source-code¶

Type

str

Description

The links to the source code of the project.

Examples

source-code:
  - https://github.com/canonical/craft-application

license¶

Type

str

Description

The project’s license as an SPDX expression.

Currently, only SPDX 2.1 expressions are supported.

For “or later” and “with exception” license styles, refer to Appendix V of the SPDX Specification 2.1.

Examples

license: GPL-3.0+

license: Apache-2.0

contact¶

Type

str | list[str]

Description

The author’s contact links and email addresses.

Examples

contact:
  - contact@example.com
  - https://example.com/contact

issues¶

Type

str | list[str]

Description

The links and email addresses for submitting issues, bugs, and feature requests.

Examples

issues:
  - issues@example.com
  - https://example.com/issues

adopt-info¶

Type

str

Description

Selects a part to inherit metadata from.

Examples

adopt-info: foo-part

package-repositories¶

Type

list[dict[str, Any]]

Description

The APT package repositories to use as sources for build and stage packages.

The Debian, Personal Package Archive (PPA), and Ubuntu Cloud Archive (UCA) package formats are supported.

Examples

package-repositories:
  - type: apt
    components:
      - main
    suites:
      - xenial
    key-id: 78E1918602959B9C59103100F1831DDAFC42E99D
    url: http://ppa.launchpad.net/snappy-dev/snapcraft-daily/ubuntu

environment¶

Type

dict[str, str]

Description

Additional environment variables for the base image’s OCI environment.

run-user¶

Type

One of: ['_daemon_']

Description

The default OCI user. Must be a shared user.

Currently, the only supported shared user is _daemon_ (UID/GID 584792). If unset, the user root (UID/GID 0) is selected as the default OCI user.

services¶

Type

dict[str, Service]

Description

Services to run in the rock.

This map of services is added to the Pebble configuration layer conforming to the layer specification.

entrypoint-service¶

Type

str

Description

The optional name of the Pebble service to serve as the OCI entrypoint.

Caution

Only set this key when the deployment environment has a container image entrypoint that is guaranteed to be static.

If set, this makes Rockcraft extend ["/bin/pebble", "enter"] with ["--args", "<serviceName>"]. The command of the Pebble service must contain an optional argument that will become the OCI CMD.

This key is mutually incompatible with the entrypoint-command key.

Examples

entrypoint-service: my-service

entrypoint-command¶

Type

str

Description

Overrides the rock’s default Pebble OCI entrypoint and CMD properties.

Important

Only set this key for certain categories of general-purpose rocks where Pebble services aren’t appropriate, such as the Ubuntu OS and base images.

The value can be suffixed with default entrypoint arguments using square brackets ([]). These entrypoint arguments become the rock’s OCI CMD.

This key is mutually incompatible with the entrypoint-service key.

Examples

entrypoint-command: echo [ Hello ]

checks¶

Type

dict[str, str]

Description

Health checks for this rock.

extensions¶

Type

list[str]

Description

The extensions to use in this project. During packing, the boilerplate keys from the listed extensions will be added to the project file.

Examples

extensions:
  - expressjs-framework

Platform keys¶

platforms¶

Type

dict[str, Platform]

Description

Determines which architectures the project builds and runs on.

If the platform name is a valid Debian architecture, the build-on and build-for keys can be omitted.

The platform name describes a build-on-build-for pairing. When setting build-on and build-for, the name is arbitrary but it’s recommended to match the platform name to the architecture set by build-for.

Examples

platforms:
  amd64:
    build-on:
      - amd64
    build-for:
      - amd64
  arm64:
    build-on:
      - amd64
      - arm64
    build-for:
      - arm64

platforms.<platform-name>.build-on¶

Type

str | list[str]

Description

Architectures to build on.

This list must contain unique values. If this field is a string containing the build-on architecture, it will be parsed at runtime into a single-entry list.

Examples

build-on: amd64

build-on:
  - arm64
  - riscv64

platforms.<platform-name>.build-for¶

Type

str | list[str]

Description

Target architecture for the build.

If this field is a string containing the target architecture, it will be parsed at runtime into a single-entry list. build-for is optional if the name of the platform is a valid build-for entry, but the model will contain the correct value.

Examples

build-for: amd64

build-for:
  - riscv64

Part keys¶

parts¶

Type

dict[str, Part]

Description

The self-contained software pieces needed to create the final artifact.

A part’s behavior is driven by its plugin. Custom behavior can be defined with the override- keys.

Examples

parts:
  cloud-init:
    plugin: python
    source-type: git
    source: https://git.launchpad.net/cloud-init

parts.<part-name>.plugin¶

Type

str

Description

The plugin to build the part with.

During the build step, the plugin prepares the part’s files with the build system of its language or framework.

Examples

plugin: python

plugin: dump

parts.<part-name>.after¶

Type

list[str]

Description

The parts to process before starting this part’s build.

During the build step, this part waits for all of the listed parts to reach the stage step before it begins building.

The purpose of this key is to stagger the part processing order so that interrelated parts can provide data to each other.

When this key is set, the part queue follows modified rules during the lifecycle:

Parts are processed alphabetically by name.
When the build reaches a part that another depends on, the dependent part will only start its build and stage steps after the initial part finishes its stage step.
After the string of dependent parts completes their lifecycles, the queue continues to the next part in alphabetical order.

Examples

after:
  - build-deps
  - daemon

parts.<part-name>.disable-parallel¶

Type

bool

Description

Whether to disable CPU multithreading during the build step.

If unset, the build defaults to multithreading.

Examples

disable-parallel: true

parts.<part-name>.source¶

Type

str

Description

The location of the source files for the part.

During the pull step, these files are placed in the part’s build environment.

Enter either an HTTP/HTTPS URL or the path to the local project directory.

Examples

source: .

source: https://github.com/canonical/dqlite

parts.<part-name>.source-type¶

Type

str

Description

The format of the part’s source.

During the pull step, the part expects the source to behave like the specified format.

If unset, the part attempts to auto-detect the format.

Supported formats include container types like .tar files and Debian packages, version-controlled directories like Git repositories, and local files.

Values

Value	Description
`deb`	Debian package
`git`	Git repository
`rpm`	Red Hat package
`snap`	Snap container format
`tar`	Tarball archive
`zip`	ZIP file
`local`	Local directory or file in the project directory
`file`	A “plain” file retrieved from the internet

Examples

source-type: git

source-type: local

parts.<part-name>.source-checksum¶

Type

str

Description

The checksum of the downloaded source, to ensure integrity.

During the pull step, the part compares the checksum against that of the downloaded files.

Checksums can be generated with any of the hashing algorithms supported by Python’s hashlib.

Examples

source-checksum: sha256/1451d01ee3a21100340aed867d0b799f46f0b1749680028d38c3f5d0128fb8a7

parts.<part-name>.source-branch¶

Type

str

Description

If the source is a Git repository, this key specifies the target branch.

During the pull step, the part fetches the repository from the earliest available commit up to the tip of this branch.

The commit history can be truncated by specifying a source-depth.

This key is mutually incompatible with source-commit and source-tag.

Examples

source-branch: main

source-branch: hotfix/2.10

parts.<part-name>.source-tag¶

Type

str

Description

If the source is a Git repository, this key specifies the target tag.

During the pull step, the part fetches the repository from the earliest available commit up to the commit with this tag.

The commit history can be truncated by specifying a source-depth.

This key is mutually incompatible with source-branch and source-commit.

Examples

source-tag: 1.0.1

parts.<part-name>.source-commit¶

Type

str

Description

If the source is a Git repository, this key specifies the target commit. Both short and long SHA hashes are supported.

During the pull step, the part fetches the repository from the earliest available commit up to this commit.

The commit history can be truncated by specifying a source-depth.

This key is mutually incompatible with source-branch and source-tag.

Examples

source-commit: 36086af03fc4941a8ac219648ce77401743f3ae0

parts.<part-name>.source-depth¶

Type

int

Description

If the source is a Git repository, this key specifies how far back in the commit history to fetch.

During the pull step, the part fetches the repository from the specified commit up to the target commit, the target tag, or the tip of the target branch.

Equivalent to the --depth parameter of git fetch.

If unset, the part fetches the full repository history up to the target commit, the target tag, or the tip of the target branch.

Examples

source-depth: 1

parts.<part-name>.source-submodules¶

Type

list[str]

Description

If the source is a Git repository, this key specifies the registered Git submodules that the project also needs.

During the pull step, the part fetches these submodules.

Equivalent to the --recurse-submodules parameter of git clone.

If unset, the part will fetch all of the repository’s submodules.

Examples

source-submodules:
  - third_party/googletest
  - third_party/jsoncpp

source-submodules:
  - libbpf

parts.<part-name>.source-subdir¶

Type

str

Description

The subdirectory of the unpacked source where the build will occur.

During the build step, build commands are restricted to the specified path.

If unset, the build can access the entire file tree of the source.

This key does not affect commands specified with override-build.

Examples

source-subdir: src

source-subdir: demo_nodes_cpp

parts.<part-name>.override-pull¶

Type

str

Description

The commands to run instead of the default behavior of the pull step.

The standard pull step actions can be performed by calling craftctl default.

Examples

override-pull: |
  craftctl default
  rm $CRAFT_PART_SRC/pyproject.toml

parts.<part-name>.overlay¶

Type

list[str]

Description

The files to copy from the part’s layer to the stage directory.

During the overlay step, files listed under this key are kept in the part’s layer unless prefixed with -, which removes them. Any files left in the part’s layer are copied to the stage directory during the stage step.

This operation only applies to files that are present in the part’s layer – files in lower layers aren’t affected. If a file is removed and a lower layer contains a file with the same path, the latter will be copied to the stage directory.

Paths support wildcards (*) and must be relative to the working directory where they will be used.

Examples

overlay:
  - bin
  - usr/bin

overlay:
  - -etc/cloud/cloud.cfg.d/90_dpkg.cfg

parts.<part-name>.overlay-packages¶

Type

list[str]

Description

The packages to install in the part’s layer.

During the overlay step, these packages are installed into the part’s layer using the base layer’s package manager.

Examples

overlay-packages:
  - ed

parts.<part-name>.overlay-script¶

Type

str

Description

The commands to run after the part’s overlay packages are installed.

If unset, the part’s layer will only contain the packages specified in overlay-packages.

Examples

overlay-script: |
  rm -f ${CRAFT_OVERLAY}/usr/bin/vi ${CRAFT_OVERLAY}/usr/bin/vim*
  rm -f ${CRAFT_OVERLAY}/usr/bin/emacs*
  rm -f ${CRAFT_OVERLAY}/bin/nano

parts.<part-name>.build-environment¶

Type

list[dict[str, str]]

Description

The environment variables to define for the build step, as key-value pairs.

Examples

build-environment:
  - MESSAGE: Hello world!
  - NAME: Craft Parts

parts.<part-name>.build-attributes¶

Type

list[str]

Description

Special identifiers that change some features and behaviors during the build.

Values

Value	Description
`enable-usrmerge`	Fills the `${CRAFT_PART_INSTALL}` directory with a merged `/usr` directory before running the part’s build step.
`disable-usrmerge`	Prevents a merged `/usr` directory from being assembled for the build step. Available in lifecycles in which the directory would be merged by default.

Examples

build-attributes:
  - enable-usrmerge

build-attributes:
  - disable-usrmerge

parts.<part-name>.override-build¶

Type

str

Description

The commands to run instead of the default behavior of the build step.

The standard build step actions can be performed by calling craftctl default.

Excluding craftctl default, these commands don’t respect the source-subdir value and are executed on the source’s root directory.

Examples

override-build: |
  cd cmd/webhook
  mkdir $CRAFT_PART_INSTALL/ko-app
  go build -o $CRAFT_PART_INSTALL/ko-app/webhook -a .

parts.<part-name>.build-packages¶

Type

list[str]

Description

The packages to install during the build step, before the build starts. The part installs them into the build environment using the host’s native package manager.

Build packages must be listed by their name on the host system.

Examples

build-packages:
  - git
  - libffi-dev
  - libssl-dev

parts.<part-name>.build-snaps¶

Type

list[str]

Description

The snaps to install during the build step, before the build starts. The part makes them available in the build environment.

Entries can be listed in one of three formats.

<snap-name>
<snap-name>/<channel-name>
<snap-name>/<channel-name>/<version-name>

If no version or channel is provided, latest/stable is used.

Examples

build-snaps:
  - go/latest/stable
  - node/stable

parts.<part-name>.organize¶

Type

dict[str, str]

Description

A map of files from the build directory to their destinations in the stage directory.

Each pair of source and destination paths is represented as a nested key of the form <source-path>: <destination-path>.

At the end of the build step, the files at the source paths are copied to their destination paths in the stage directory.

Examples

organize:
  hello.py: bin/hello

parts.<part-name>.stage¶

Type

list[str]

Description

During the stage step, any specified files are copied from the build directory to the stage directory.

Paths support wildcards (*) and must be relative to the working directory where they will be used.

Examples

stage:
  - usr/bin/*
  - usr/share

stage:
  - -usr
  - zfsutils-linux

parts.<part-name>.stage-packages¶

Type

list[str]

Description

During the stage step, these packages are included in the stage environment alongside the build artifacts.

Chisel slices can be listed using the <package-name>_<slice-name> syntax.

Listing both packages and slices in the same stage-packages key is not currently supported.

Examples

stage-packages:
  - curl
  - libxml2

parts.<part-name>.stage-snaps¶

Type

list[str]

Description

During the stage step, these snaps are included in the stage environment.

Entries can be in one of three formats:

<snap-name>
<snap-name>/<channel-name>
<snap-name>/<channel-name>/<version-name>

If an entry contains no version or channel, latest/stable is used.

Examples

stage-snaps:
  - go/1.17
  - chisel/latest/candidate
  - mir-kiosk-x11

parts.<part-name>.override-stage¶

Type

str

Description

The commands to run instead of the default behavior of the stage step.

The standard stage step actions can be performed by calling craftctl default.

Examples

override-stage: |
  craftctl default
  chown -R 499 "${CRAFT_PART_INSTALL}/entrypoint.sh"

parts.<part-name>.prime¶

Type

list[str]

Description

During the prime step, any specified files are copied from the stage directory to the final payload.

Paths support wildcards (*) and must be relative to the working directory where they will be used.

Examples

prime:
  - usr/lib/*/qt6/plugins/tls/*
  - -usr/share/thumbnailers

parts.<part-name>.override-prime¶

Type

str

Description

The commands to run instead of the default behavior of the prime step.

The standard prime step actions can be performed by calling craftctl default.

Examples

override-prime: |
  craftctl default
  mkdir -p $CRAFT_PRIME/var/lib/mysql
  mkdir -p $CRAFT_PRIME/var/lib/mysqld

parts.<part-name>.permissions¶

Type

list[Permissions]

Description

The ownership and permission settings for a set of files in the part’s prime directory.

The files at path will be assigned an owner and a group, with the read, write, and execute permissions of each being determined by the value of mode.

Examples

permissions:
  - owner: 2000
    group: 2000
  - path: srv/indico/start-indico.sh
    mode: '544'
  - path: etc/
    mode: '755'

parts.<part-name>.permissions.<permission>.path¶

Type

str

Description

The file path, relative to the prime directory, being assigned permissions.

Wildcards (*) are supported.

If unset, the permissions will be assigned to every file in the prime directory.

parts.<part-name>.permissions.<permission>.owner¶

Type

int

Description

The numeric user ID (UID) of the desired owner on the host system.

This entry is required if the permissions contain a group entry.

parts.<part-name>.permissions.<permission>.group¶

Type

int

Description

The numeric group ID (GID) of the desired owner group on the host system.

This entry is required if the permissions contain an owner entry.

parts.<part-name>.permissions.<permission>.mode¶

Type

str

Description

The numeric representation of the file’s read, write, and execute permissions.

This entry must be assigned an octal number, enclosed in double-quotation marks ("), for each defined path.

This value should align with the POSIX specification for file permissions, just like one would use when calling chmod. For more detail on octal file permissions, see the chmod command reference.