snapcraft.yaml¶

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

For keys that refer to file and directory locations, paths are always relative to the snap’s file system, not the host.

Top-level keys¶

The top-level keys dictate the snap’s packaging information and the essential details of how it builds.

Top-level details include a snap’s name, version and description, alongside operational values such as its confinement level and supported architectures.

name¶

Type

str

Description

The identifying name of the snap.

It must start with an ASCII character and can only contain lower case letters, numbers, and hyphens. It must contain at least one letter and it can’t start or end with a hyphen. The maximum length is 40 characters.

The name must be unique if you want to publish it to the Snap Store.

For help on choosing a name and registering it on the Snap Store, see Register a snap.

Examples

name: my-app

name: powershell

name: jupyterlab-desktop

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

version¶

Type

str

Description

The version of the snap.

This field is required unless version information is provided by the adopt-info key.

See Configure package information for details.

Examples

version: 1.2.3

license¶

Type

str

summary¶

Type

str

Description

A short description of your project.

Examples

summary: Linux for Human Beings

summary: The cross-platform desktop application for JupyterLab

summary: Container and VM manager

summary: Photo Management Program

summary: Charm for routing MySQL databases in Kubernetes

summary: An open-source event streaming platform for high-performance data pipelines

description¶

Type

str

adopt-info¶

Type

str

Description

Selects a part to inherit metadata from and reuse for the snap’s metadata.

Required if one of version, summary, or description isn’t set.

There are two ways to adopt metadata from a part:

Using the ‘craftctl set’ command in an ‘override-’ script.
Using appstream metadata files listed in the ‘parse-info’ field of the adopting part.

Examples

adopt-info: foo-part

type¶

Type

One of: ['app', 'base', 'gadget', 'kernel', 'snapd']

Description

The snap’s type.

Values

Value	Description
`app`	Default. Set the snap as an application.
`base`	Set the snap as a base.
`gadget`	Set the snap as a gadget snap.
`kernel`	Set the snap as a kernel snap.
`snapd`	Set the snap as a snapd snap.

Examples

type: kernel

base¶

Type

str

build-base¶

Type

str

Description

The build environment to use when building the snap

Examples

build-base: core20

build-base: core22

build-base: core24

build-base: devel

grade¶

Type

One of: ['stable', 'devel']

Description

The quality grade of the snap.

The grade can only be stable if the base and build-base are stable. For example, if the build-base is devel, then the grade must be devel.

The grade must be stable to publish the snap to the candidate or stable channels on the snap store. If the grade is devel, it can only be published to the beta and edge channels.

Values

Value	Description
`stable`	Default. The snap is stable.
`devel`	The snap is still under development.

Examples

grade: stable

grade: devel

confinement¶

Type

One of: ['classic', 'devmode', 'strict']

Description

The amount of isolation the snap has from the host system.

Snap confinement determines the amount of access an application has to system resources, such as files, the network, peripherals and services.

For core22 and newer bases, confinement is a required property and has no default value.

For more information, see Confinement.

Values

Value	Description
`strict`	Default for core20 and older bases. Use strict confinement.
`classic`	Use classic confinement.
`devmode`	Use devmode confinement.

Examples

confinement: strict

confinement: classic

confinement: devmode

source-code¶

Type

list[str]

Description

The links to the source code of the snap or the original product.

Source code links can be adopted from appstream metadata files.

See Reuse information for details.

Examples

source-code:
  - https://example.com/source-code

contact¶

Type

list[str]

Description

The snap author’s contact links and email addresses.

Contact information can be adopted from appstream metadata files.

See Reuse information for details.

Examples

contact:
  - [email protected]
  - https://example.com/contact

website¶

Type

list[str]

Description

The links to the original software’s web pages.

Websites can be adopted from appstream metadata files.

See Reuse information for details.

Examples

website:
  - https://example.com

issues¶

Type

list[str]

Description

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

Issue links can be adopted from appstream metadata files.

See Reuse information for details.

Examples

issues:
  - [email protected]
  - https://example.com/issues

donation¶

Type

list[str]

Description

The snap’s donation links.

Donation links can be adopted from appstream metadata files.

See Reuse information for details.

Examples

donation:
  - [email protected]
  - https://example.com/donate

compression¶

Type

One of: ['lzo', 'xz']

Description

Specifies the algorithm that compresses the snap.

Snaps are compressed using xz data compression by default. This offers the optimal performance to compression ratio for the majority of snaps.

However, there are certain types of snap, such as large desktop applications, that can benefit from using LZO compression. Snaps compressed with LZO are slightly larger but can decompress quicker, reducing the time it takes for freshly installed or refreshed snaps to launch.

Values

Value	Description
`xz`	Default. Use XZ compression.
`lzo`	Use LZO compression.

Examples

compression: xz

compression: lzo

icon¶

Type

str

Description

The path to the snap’s icon.

Icon size can be between 40x40 and 512x512 pixels. 256x256 is recommended. The file should be less than 256 KB.

The icon is used in the snap store and other graphical store fronts. The icon defined in the .desktop file is used as the icon in desktop menus.

Examples

icon: snap/gui/icon.svg

layout¶

Type

One of: ['symlink', 'bind', 'bind-file', 'type']

Description

The file layouts in the execution environment.

Layouts modify the execution environment of a strictly-confined snap.

With layouts, you can make elements in $SNAP, $SNAP_DATA, $SNAP_COMMON accessible from locations such as /usr, /var and /etc. This helps when using pre-compiled binaries and libraries that expect to find files and directories outside of locations referenced by $SNAP or $SNAP_DATA.

See Layouts for complete details.

Values

Value	Description
`symlink: <source-path>`	Create a symbolic link. This method is preferred because it is the cheapest; the other methods significantly increase the startup time of your application
`bind: <source-path>`	Bind-mount a directory.
`bind-file: <source-path>`	Bind-mount a file.
`type: tmpfs`	Mount a private, temporary, in-memory filesystem

Examples

layout:
  /var/lib/foo:
    bind: $SNAP_DATA/var/lib/foo

passthrough¶

Type

dict[str, Any]

Description

The attributes to pass to the snap’s metadata file.

These attributes are passed to snap.yaml without validation from Snapcraft. This is useful for early testing of a new feature in snapd that isn’t yet supported by Snapcraft.

To pass a value for a particular app, see the passthrough key for apps.

See Using development features in Snapcraft.

Examples

passthrough:
  daemon: complex

assumes¶

Type

list[str]

Description

The minimum version of snapd and its features that the snap requires from the host.

If the host doesn’t meet any of the requirements, snapd won’t install the snap.

You can declare both a snapd version and its features at the same time.

List a minimum version of snapd with snapd<version>.

List required snapd features by name:

common-data-dir for the common data directory across revisions of a snap.
snap-env for declaring runtime environment variables in the project file.
command-chain for chaining commands in apps and hooks in the project file.
kernel-assets for kernel assets declared in a gadget snap project file.

Examples

assumes:
  - snapd2.66
  - common-data-dir

slots¶

Type

dict[str, Any]

Description

Declares the snap’s slots.

Examples

slots:
  slot-1:
    interface: content
    content: my-binaries
    source:
      read:
        - $SNAP/bin

lint¶

Type

Lint

Description

The linter configuration settings.

Snapcraft runs the following linters:

classic: Verifies binary file parameters for snaps using classic confinement.
library: Verifies that no ELF file dependencies, such as libraries, are missing and that no extra libraries are included in the snap package.

See Linters for more information.

Examples

lint:
  ignore:
    - classic
    - library:
        - usr/lib/**/libfoo.so*

epoch¶

Type

str

Description

The epoch associated with this version of the snap.

Controls when users receive configuration-breaking application releases and ensures upgrades migrate through each epoch.

Asterisks after the epoch denote it can read configuration data from the previous epoch.

This is an uncommonly used key.

See Manage data compatibility for more information.

Examples

epoch: 1

epoch: 2*

system-usernames¶

Type

dict[str, Any]

Description

The system usernames that the snap can use to run daemons and services.

This is used to use the snapd defined user snap_daemon run a daemon. Otherwise, this is an uncommonly used vaiue.

See system usernames for more information.

Examples

system-usernames:
  snap-daemon: shared

environment¶

Type

dict[str, str | None]

Description

The snap’s runtime environment variables.

Environment variables are set at runtime for all apps. To set an environment variable for a particular app, use the environment key for that app entry.

Examples

environment:
  PYTHONPATH: $SNAP/usr/lib/python3/dist-packages:$PYTHON_PATH
  DISABLE_WAYLAND: 1

build-packages¶

Type

GrammarScalar

Description

The list of packages to install when building a snap.

All build packages are installed before any part is built. However, if a package is only needed for one part, it is recommended to use the build-packages key for that part. This organization makes it easier to track which parts require which build packages.

Examples

build-packages:
  - libssl-dev
  - libyaml-dev

build-snaps¶

Type

GrammarScalar

Description

The snaps to install when building a snap.

If only the snap name is provided, the snap will be installed from the latest/stable channel.

Otherwise, a channel can be specified with <name>/<channel>.

Examples

build-snaps:
  - go/1.22/stable
  - yq

ua-services¶

Type

set[str]

Description

The Ubuntu Pro (formerly Ubuntu Advantage) services to enable when building the snap.

Enabling Ubuntu Pro services allows building snaps in an Ubuntu Pro enabled environment.

Examples

ua-services:
  - esm-apps

provenance¶

Type

str

Description

The primary-key header for snaps signed by third parties.

This is an uncommonly used value.

Examples

provenance: test-provenance

platforms¶

Type

dict[str, Platform]

Description

The platforms where the snap can be built and where the resulting snap can run.

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

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

The platforms key is only used in core24 and newer snaps. For core22 and older snaps, use the architectures key.

Examples

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

architectures¶

Type

list[str | Architecture]

Description

The architecture sets where the snap can be built and where the resulting snap can run.

The architectures key is only used in core22 and older snaps. For core24 and newer snaps, use the platform key.

Architectures may be defined as a shorthand list of architectures or a explicit pair of build-on/build-for entries.

Examples

architectures:
  - amd64
  - riscv64

architectures:
  - build-on:
      - amd64
    build-for:
      - amd64

architectures:
  - build-on:
      - amd64
      - riscv64
    build-for:
      - riscv64

apps¶

Type

dict[str, App]

Description

The map of app names representing entry points to run for the snap.

Apps are used to expose applications and services for the snap, how they are run, and which resources they can access.

If the app name is the same as snap name, the app will be run when the snap is run as app-name.

If they differ, the program will be exposed as ‘<snap-name>.<app-name>’.

Examples

apps:
  app-1:
    command: bin/app-1

parts¶

Type

dict[str, Part]

package-repositories¶

Type

list[dict[str, Any]]

hooks¶

Type

dict[str, Hook]

Description

Configures the snap’s hooks.

Examples

hooks:
  configure:
    plugs:
      - home

components¶

Type

dict[str, Component]

Description

Declares the components to build in conjunction with the snap.

Examples

components:
  foo-component:
    type: standard

plugs¶

Type

dict[str, ContentPlug | Any]

Description

Declares the snap’s plugs.

Examples

plugs:
  dot-gitconfig:
    interface: personal-files
    read:
      - $HOME/.gitconfig

App keys¶

The apps key declares the programs and services that a snap operates on the host, and details how they’re executed and which resources they can access.

Snapcraft project app definition.

apps.<app-name>.command¶

Type

str

Description

The command to run inside the snap when the app is invoked.

The command can be in either a snap runtime’s command path, $SNAP/usr/sbin:$SNAP/usr/bin:$SNAP/sbin:$SNAP/bin, or an executable path relative to $SNAP.

The command must consist only of alphanumeric characters, spaces, and the following special characters: /, ., _, #, :, $, -. If other characters are required, a wrapper script should be used for the command.

If the daemon is set, this will be the command to run the service. Only a snap with classic confinement can use a relative path because PATH isn’t modified by a wrapper in classic confinement. See Classic confinement for more details.

Examples

command: bin/foo-app

apps.<app-name>.autostart¶

Type

str

Description

The desktop file used to start an app when the desktop environment starts.

The desktop file is placed in $SNAP_USER_DATA/.config/autostart and the app is launched by the app’s command wrapper (<name>.<app>) plus any argument present in the Exec= line in the .desktop file when the desktop environment is started.

See Autostart desktop files for an example of both the desktop file and the Exec file entry.

Examples

autostart: foo-app.desktop

apps.<app-name>.common-id¶

Type

str

Description

The identifier to a desktop ID within an external appstream file.

See Configure package information for more information.

Examples

common-id: org.canonical.foo

apps.<app-name>.bus-name¶

Type

str

Description

The bus name that the application or service exposes through D-Bus.

Examples

bus-name: org.bluez

apps.<app-name>.desktop¶

Type

str

Description

The desktop file used to start an app.

See Configure package information for more information.

Examples

desktop: my-app.desktop

apps.<app-name>.completer¶

Type

str

Description

The name of the bash completion script for the app.

Examples

completer: bash-complete.sh

apps.<app-name>.stop-command¶

Type

str

Description

The command to run to stop the service.

Requires the daemon key to be specified for the app.

This allows a daemon to gracefully stop or restart, such as when a snap refresh occurs.

See the daemon key reference for more information.

Examples

stop-command: bin/foo-app --halt

apps.<app-name>.post-stop-command¶

Type

str

Description

The command to run after the service is stopped.

Requires the daemon key to be specified for the app.

This allows a daemon to gracefully stop or restart, such as when a snap refresh occurs.

See the daemon key reference for more information.

Examples

post-stop-command: bin/logrotate --force

apps.<app-name>.start-timeout¶

Type

str

Description

The maximum amount of time to wait for the service to start.

If the service does not start before the start-timeout elapses, then snapd will take further action based on the restart-condition key in the app.

Requires the daemon key to be specified for the app.

See the daemon key reference for more information.

Examples

start-timeout: 10s

start-timeout: 2m

apps.<app-name>.stop-timeout¶

Type

str

Description

The maximum amount of time to wait for the service to stop.

If the service does not stop before the stop-timeout elapses, then snapd will send a SIGTERM signal. If the service still does not stop, snapd will send a SIGKILL signal.

Requires the daemon key to be specified for the app.

See the daemon key reference for more information.

Examples

stop-timeout: 10s

stop-timeout: 2m

apps.<app-name>.watchdog-timeout¶

Type

str

Description

The maximum amount of time the service can run without sending a heartbeat to the watchdog.

For the watchdog to work, the application must have access to the systemd notification socket by specifying daemon-notify plug in the apps plugs definition.

Requires the daemon key to be specified for the app.

See the daemon key reference for more information.

Examples

watchdog-timeout: 10s

watchdog-timeout: 2m

apps.<app-name>.reload-command¶

Type

str

Description

The command to run to restart the service.

Requires the daemon key to be specified for the app.

See the daemon key reference for more information.

Examples

reload-command: bin/foo-app --restart

apps.<app-name>.restart-delay¶

Type

str

Description

The time to wait between service restarts.

Requires the daemon key to be specified for the app.

See the daemon key reference for more information.

Examples

restart-delay: 10s

restart-delay: 2m

apps.<app-name>.timer¶

Type

str

Description

The time or schedule to run a service.

The timer field uses a flexible syntax to schedule when a service should run.

Requires the daemon key to be specified for the app.

See the daemon key reference for more information.

Examples

timer: 1380

timer: 00:00-24:00/24

timer: mon,10:00,,fri,15:00

apps.<app-name>.daemon¶

Type

One of: ['simple', 'forking', 'oneshot', 'notify', 'dbus']

Description

Configures the app as a service, and sets its runtime and notification behavior.

See the daemon key reference for more information.

Values

Value	Description
`simple`	Run as long as the service is active. This is the most common option.
`forking`	The app’s `command` will call `fork()` as part of its start-up and the parent process is expected to exit when start-up is complete. This is used to support legacy fork-based Unix daemons.
`oneshot`	Run once and exit after completion, notifying systemd. After completion, the daemon is still considered active and running.
`notify`	Allows the service to be managed by systemd. Requires the service to send signals to the systemd notification socket by specifying `daemon-notify` in the app’s `plugs` definition.
`dbus`	Registers a D-Bus name to notify systemd. Requires ``bus-name or `activates-on` to be specified.

Examples

daemon: simple

daemon: oneshot

apps.<app-name>.after¶

Type

list[str]

Description

The ordered list of apps that the service runs after it launches.

The apps must be part of the same snap.

Requires the daemon key to be specified for the app. Apps in the after key must also specify the daemon key.

See the daemon key reference for more information.

Examples

after:
  - foo-app
  - bar-app

apps.<app-name>.before¶

Type

list[str]

Description

The ordered list of apps that the service runs before it launches.

The apps must be part of the same snap.

Requires the daemon key to be specified for the app. Apps in the before key must also specify the daemon key.

See the daemon key reference for more information.

Examples

before:
  - baz-app
  - quz-app

apps.<app-name>.refresh-mode¶

Type

One of: ['endure', 'restart', 'ignore-running']

Description

Determines how the service should restart when the snap refreshes.

Requires the daemon key to be specified for the app.

See the daemon key reference for more information.

Values

Value	Description
`restart`	Restart the service when the snap is refreshed. Default.
`endure`	Do not restart the service when the snap is refreshed.
`ignore-running`	Do not refresh the snap if the service is running.

Examples

refresh-mode: restart

apps.<app-name>.stop-mode¶

Type

One of: ['sigterm', 'sigterm-all', 'sighup', 'sighup-all', 'sigusr1', 'sigusr1-all', 'sigusr2', 'sigusr2-all', 'sigint', 'sigint-all']

Description

The signal to send when stopping the service.

Requires the daemon key to be specified for the app.

See the daemon key reference for more information.

Examples

stop-mode: sigterm

apps.<app-name>.restart-condition¶

Type

One of: ['on-success', 'on-failure', 'on-abnormal', 'on-abort', 'on-watchdog', 'always', 'never']

Description

The conditions that cause the service to restart.

The conditions for restart-condition match those defined by systemd. See the systemd manual for information on what exit codes will trigger a restart for each condition.

Requires the daemon key to be specified for the app.

See the daemon key reference for more information.

Examples

restart-condition: on-failure

apps.<app-name>.install-mode¶

Type

One of: ['enable', 'disable']

Description

Whether snapd can automatically start the service when the snap is installed.

Requires the daemon key to be specified for the app.

See the daemon key reference for more information.

Values

Value	Description
`enable`	The service is started when the snap is installed. Additionally, if the snap was installed without a service, then the snap is refreshed to include a service. This will start the service too.
`disable`	The service is not automatically started. Instead, the service will be started with craftctl and another management agent, which is most commonly a hook.

Examples

install-mode: enable

apps.<app-name>.slots¶

Type

list[str]

Description

The list of slots that the app provides.

Slot connections are only made when the snap is running in strict confinement.

Slots are used to define what code and data can be shared with other snaps.

See the content interface for more information about plugs and slots.

Examples

slots:
  - dbus-daemon

apps.<app-name>.plugs¶

Type

list[str]

Description

The list of interfaces that the app can connect to.

See the content interface for more information about plugs and slots.

Examples

plugs:
  - home
  - removable-media

apps.<app-name>.aliases¶

Type

list[str]

Description

The aliases that can be used to run the app.

See Commands and aliases for more information.

Examples

aliases:
  - my-app

apps.<app-name>.environment¶

Type

dict[str, str]

Description

The runtime environment variables.

To set an environment variable for all apps, use the top-level environment key.

Examples

environment:
  PYTHONPATH: $SNAP/usr/lib/python3/dist-packages
  DISABLE_WAYLAND: 1

apps.<app-name>.command-chain¶

Type

list[str]

Description

The ordered list of commands to run before the app’s command runs.

Command chains are useful to run setup scripts before running an app.

Examples

command-chain:
  - bin/alsa-launch
  - bin/desktop-launch

apps.<app-name>.sockets¶

Type

dict[str, Socket]

Description

The sockets used to activate an app.

Requires the network-bind interface in the app’s plug key.

This value is used for services that are activated by a connection to a socket.

Examples

sockets:
  my-socket:
    listen-stream: $SNAP_COMMON/lxd/unix.socket
    socket-mode: 432

apps.<app-name>.daemon-scope¶

Type

One of: ['system', 'user']

Description

Determines whether the service is run on a system or a user instance of systemd.

See Enabling user daemons for more information on how snapd manages daemon scope.

Requires the daemon key to be specified for the app.

See the daemon key reference for more information.

Values

Value	Description
`system`	Run the service under the system instance of systemd.
`user`	Run the service under a user-session instance of systemd.

Examples

daemon-scope: user

apps.<app-name>.activates-on¶

Type

list[str]

Description

The slots exposed by the snap to activate the service with D-Bus.

This is useful for services that are activated by other applications or services.

See D-Bus activation for more information on how snapd activates services with D-Bus.

Requires the daemon key to be specified for the app.

See the daemon key reference for more information.

Examples

activates-on: gnome-shell-dbus

apps.<app-name>.passthrough¶

Type

dict[str, Any]

Description

The attributes to pass to the snap’s metadata file for the app.

Attributes to passthrough to snap.yaml without validation from Snapcraft. This is useful for early testing of a new feature in snapd that isn’t supported yet by Snapcraft.

To pass a value for the entire project, see the top-level passthrough key.

See Using development features in Snapcraft for more details.

Examples

passthrough:
  daemon: complex

Part keys¶

The parts key and its values declare the snap’s parts and detail how they’re built.

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.

For more details on plugin-specific keys and dependencies, see Plugins.

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 pull step, the build will be restricted to the specified path.

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

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.

For more details on overriding lifecycle steps and using craftctl, see Override a step.

Examples

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

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

The part’s default behavior for executable patching is dependent on the base snap. The following options alter the behavior.

Values

Value	Description
`core22-step-dependencies`	For snaps using core20. Orders lifecycle steps as they are ordered for core22 and newer snaps.
`enable-patchelf`	For classically-confined snaps using core22 and newer. Patches executables for files primed by the part. By default, executables primed by the part aren’t patched.
`no-patchelf`	For classically-confined snaps using core20. Disables executable patching for files primed by the part. If unset, patches all executables primed by the part.
`keep-execstack`	For snaps using core20. Retains the execstack for executables primed by the part.

For core20 snaps, the core22-step-dependencies customization alters the part processing order to align with newer bases, where all parts are pulled prior to build. For more details on part processing for core22 and newer, see Processing order and dependencies.

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.

For more details on overriding lifecycle steps and using craftctl, see Override a step.

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

Files from the build environment can be organized into specific components. The destination path must start with (component/<component-name>), with the parentheses included. Source paths always reference the default build environment.

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.

For more details on file paths, see Specifying paths.

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.

For more details on overriding lifecycle steps and using craftctl, see Override a step

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.

For more details on file paths, see Specifying paths.

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.

For more details on overriding lifecycle steps and using craftctl, see Override a step

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.

Socket keys¶

Snapcraft app socket definition.

sockets.<socket-name>.listen-stream¶

Type

int

Description

The socket’s abstract name or socket path.

TCP and UNIX sockets are supported.

Examples

listen-stream: $SNAP_COMMON/lxd/unix.socket

listen-stream: 80

sockets.<socket-name>.socket-mode¶

Type

int

Description

The mode or permissions of the socket in octal.

Examples

socket-mode: 432

Hook keys¶

Snapcraft project hook definition.

hooks.<hook-type>.command-chain¶

Type

list[str]

Description

The ordered list of commands to run before the hook runs.

Command chains are useful to run setup scripts before running a hook.

Examples

command-chain:
  - bin/alsa-launch
  - bin/desktop-launch

hooks.<hook-type>.environment¶

Type

dict[str, str | None]

Description

The environment variables for the hook.

Examples

environment:
  PYTHONPATH: /custom/path/:$PYTHON_PATH
  DISABLE_WAYLAND: 1

hooks.<hook-type>.plugs¶

Type

list[str]

Description

The list of interfaces that the hook can connect to.

See the content interface for more information about plugs and slots.

Examples

plugs:
  - home
  - removable-media

hooks.<hook-type>.passthrough¶

Type

dict[str, Any]

Description

The attributes to pass to the snap’s metadata file for the hook.

Attributes to passthrough to snap.yaml without validation from Snapcraft. This is useful for early testing of a new feature in snapd that isn’t supported yet by Snapcraft.

To pass a value for the entire project, see the top-level passthrough key.

See Using development features in Snapcraft for more details.

Examples

passthrough:
  daemon: complex

Component keys¶

Snapcraft component definition.

components.<component-name>.summary¶

Type

str

Description

The summary of the component.

This is a freeform field used to describe the purpose of the component.

Examples

summary: Language translations for the app

components.<component-name>.description¶

Type

str

Description

The multi-line description of the component.

This is a freeform field used to describe the purpose of the component.

Examples

description: Contains optional translation packs to allow the user to change the language.

components.<component-name>.type¶

Type

One of: ['test', 'kernel-modules', 'standard']

Description

The type of the component.

Different component types may have special handling by snapd.

Values

Values	Description
`standard`	General use type. Use when no specific type applies.
`kernel-modules`	For kernel modules in snaps with type `kernel`.

Examples

type: standard

components.<component-name>.version¶

Type

str

Description

The version of the component.

If the version is not provided, the component will be unversioned.

Examples

version: 1.2.3

components.<component-name>.hooks¶

Type

dict[str, Hook]

Description

The configuration for the component’s hooks.

Examples

hooks:
  configure:
    plugs:
      - home

Content plug keys¶

Snapcraft project content plug definition.

plugs.<plug-name>.content¶

Type

str

Description

The name for the content type.

This is an arbitrary identifier for content interfaces. If it is not specified, it will default to the plug’s name.

Examples

content: themes

plugs.<plug-name>.interface¶

Type

str

Description

The name of the interface.

See Supported interfaces for a list of supported interfaces.

When using the content interface, this should be set to content.

Examples

interface: network

plugs.<plug-name>.target¶

Type

str

Description

The path to where the producer’s files will be available in the snap.

This is only needed when using the content interface. See the Content interface for more information.

Examples

target: $SNAP/data-dir/themes

plugs.<plug-name>.default-provider¶

Type

str

Description

The name of the producer snap.

This is only needed when using the content interface. See the Content interface for more information.

Examples

default-provider: gtk-common-themes