Build options

doc
1

By default, Snapcraft uses LXD or Multipass to build within a confined virtual machine on local or remote systems. For most developers, this happens transparently and is the best way to build snaps. The build also has the flexibility to operate on other architectures, frameworks, and distributed computing services, and so offers a number of options for how and where you want it to run. These are outlined below.

Supported build options

Applies to builds using core22 and later

Build option Description Requirements
snapcraft The default build on the local host. On Linux, uses LXD for the virtual environment.1 On macOS and Windows, uses Multipass. The snap is built within an instantiated VM to ensure a clean and isolated environment. Nested VMs require accelerated or nested VM functionality. Any supported system with VM capabilities.
snapcraft remote-build A multi-architecture build on remote servers using Launchpad. Prospective snaps must be open source as the code will be publicly available by default. You also need a Launchpad account to orchestrate the build.
Build from GitHub A remote build that triggers automatically in conjunction with authentication from a Ubuntu One developer account. Requires the snap source to be hosted on a public GitHub repository, and for your GitHub account and developer account to be linked.
electron-builder -l snap A build using the Electron framework. You can create snaps with a simple modification to the package.json file. Linux or macOS. Requires electron-builder.

1 Snaps built on Linux with core, core18, and core20 use Multipass as the default build provider.

Change and configure build providers

See Build providers for information on how to configure Snapcraft to switch between LXD and Multipass, and make use of provider-specific options.

Build environment options

Snapcraft can optionally use the following arguments to modify the build environment.

Snapcraft argument Description Requirements
--destructive-mode Destructive mode. Designed to be used in scenarios where additional provisioning of the build environment is required. This is not recommended because the build could contaminate the host build environment. See the Destructive Mode section below.
--use-lxd LXD container. Builds the snap using LXD, rather than Multipass. This can potentially reduce resource usage, especially from a VM.
Set SNAPCRAFT_BUILD_ENVIRONMENT=lxd to use LXD by default.		 Requires LXD
--http-proxy <http-proxy> Configures HTTP proxy. Snapcraft will honour http_proxy environment flag as well. None
--https-proxy <https-proxy> Configures HTTPS proxy. Snapcraft will honour https_proxy environment flag as well. None
--add-ca-certificates <path> Adds trusted CAs in Snapcraft-created build environments. May be a CA certificate file or directory containing certificate files.
Not currently compatible with Snapcraft 7.x		 LXD, Multipass
--bind-ssh Bind ~/.ssh directory to local build instance. LXD, Multipass
--ua-token Configure build environment with ESM using specified UA token. LXD, Multipass

Destructive mode

Destructive mode builds the snap directly on the machine where snapcraft is run without launching a LXD or Multipass container. It is not recommended to use because Snapcraft cannot control the build environment. It is especially not recommended to use on a personal machine or in a shared environment, where operations like adding package repositories may be disruptive.

The build environment should match the snap base. For example, a core24 snap should be built inside an Ubuntu 24.04 environment.

For core22 and newer snaps, the user must have root-level permissions so that they can do operations such as installing snaps and apt packages and adding package repositories without needing to use sudo.

While destructive mode can be used in CI to save time, using an OCI image or a LXD container is recommended. See snapcraft-rocks for OCI images that can be used with Docker to build snaps. For projects in Github, the canonical/action-build workflow is a good option.

Deprecated build options

Command Description Requirements
snapcraft cleanbuild Cleanbuild. Legacy non-bases method for building snaps in a LXD container. Deprecated with the release of Snapcraft 3.x and no longer supported.
apt install snapcraft Snapcraft deb package. Originally used to install snapcraft on Ubuntu-based Linux distributions (and Debian). Outdated and no longer supported. See Snapcraft overview for current installation instructions.
snapcraft --offline Allow snapcraft to build snaps on a system without a network connection provided that 1) the build environment is prepared, and 2) all sources and packages required by the parts are already on the local system (that usually means that snapcraft pull was successfully executed when networking was still available). None

Deprecated Snapcraft argument

Snapcraft argument Description Requirements
--enable-manifest Deprecated and removed in core24. Add the build manifest to the snap package in snap/manifest.yaml. This contains the specific sources and packages used to build the snap and allows the Snap Store to automatically check your Snap for security issues. Setting the environment variable SNAPCRAFT_BUILD_INFO=1 to add build manifest is still supported. Snaps built on Launchpad will have this set automatically. None

A supported Linux system is a host or VM running a snap-capable Linux distribution. See Installing snapd for details.

4 Likes
2

This page probably needs updating for Snapcraft 7, as the default is now LXD (not Multipass). Also, destructive mode can be set via env var SNAPCRAFT_BUILD_ENVIRONMENT=host. Among other things.

3

The default is only LXD if you’re using core22 as your base snap, IIRC?

4

Hmmm … that might be correct, I will check.

5

@lucyllewy is correct. I updated the docs.

1 Like
6

Should this page include the recent “snapcraft try” command?

7

I don’t think “–enable-manifest” is in development anymore, is it? It’s pretty much stable.

8

Thanks, and I think you’re right. I’ll also add something on snapcraft try.

9

This option does not seem to be supported using snapcraft 7.3.1:

snapcraft --add-ca-certificates /usr/local/share/ca-certificates...
Usage: snapcraft [options] command [args]...
Try 'snapcraft pack -h' for help.

Error: unrecognized arguments: --add-ca-certificates
1 Like
10

Hi @nicolasbock,

We’re tracking that bug here: https://bugs.launchpad.net/snapcraft/+bug/2004072

1 Like
11

The rendered page at https://snapcraft.io/docs/build-options has some kind of style which makes the run-on text turn into ellipses instead of wrapping to the next line. Not sure if other pages are affected.

Here’s what I see on my monitor:

image
image799Ă—390 41.3 KB

12

Thanks so much for letting us know. It looks like the rendering style for the table output changed. We have no direct control over this, or the cell widths in a table, but I’ll bring it up with the web team.

For now, I’ve edited the table so the ellipses should no longer be needed/generated.

1 Like
13

Is this set of requirements for --destructive-mode outdated?

14

Good catch, I updated it.

2 Likes
15

The --http-proxy and --https-proxy command-line options are no longer supported in core24.

16

Hi @degville , I’ve just fixed a broken link in this sentence:

Uses LXD or Multipass to builds the snap …

1 Like
17

@Lin-Buo-Ren, I believe that is a regression. Would you file a bug at Sign in to GitHub · GitHub? Thanks!

1 Like
18

Sure thing! I’ve filed it here: No longer be able to use HTTP(S) proxies when building core24 snaps · Issue #4893 · canonical/snapcraft

2 Likes
19

This could benefit from an update. LXD is the default nowadays. Setting --use-lxd is no longer that useful. Maybe when default is changed to multipass via the env and the user wants to override it to LXD?

No documentation on how to use multipass. SNAPCRAFT_BUILD_ENVIRONMENT=multipass?

20

Perhaps we could drop the details about LXD and Multipass from this page and make the link to https://snapcraft.io/docs/build-providers more prominent?