Ubuntu Core images

Official Ubuntu Core images for supported devices can be found here.

Install Ubuntu Core on your device ›

Build a custom Ubuntu Core image

This document will walk you through all the steps to build an image for a device family. You will learn how to:

  • Create and upload a snapcraft key to the store
  • Create a model assertion for your target device
  • Compose and build a custom image using the ubuntu-image command

If you want to build an Ubuntu Core image for a board that is not already supported, please follow the Board enablement overview document.

Snapcraft keys

Before starting with building the image, you need to create a key to sign your future store uploads.

1. Create a key

Note: If you are building an image to work with a Brand Store, you need to use the Brand SSO account for these steps. You can use snapcraft logout. Then use snapcraft login and provide the Brand SSO Account credentials to login.

As a first step, you have to generate a key that will be linked to your Ubuntu Store account. To do so, run:

snapcraft create-key

You can pass an optional name for the key:

snapcraft create-key foo

This command will ask you for a password to protect the key.

It will take some time, as it's creating a 4096 bit long key and needs some entropy to complete. To speed up the process, you can install the rng-tools package beforehand.

Now, you can list your keys with:

snapcraft list-keys

2. Register the key with the store

Next, you have to register the key with the store, effectively linking it to your account. During this step, you will be asked to select an existing key and login with your store account credentials.

snapcraft register-key

The key is now registered with the store and you can start the actual image building.

Image building

An ubuntu-core image is composed of at least three snaps installed together: OS, gadget and kernel.

  • The OS snap contains ubuntu-core itself and will be downloaded during image creation.
  • The kernel and gadget snaps are layers to personalize or enable your target device. They can be locally built or pulled from the store if they already exist.

The composition of your image is described through a "model assertion", a signed JSON document.

1. Create a model assertion

To build an image, it is required you have a signed model assertion.


As an example, here is one for a device based on a Raspberry Pi 3 board. The JSON file is named pi3-model.json, with the following content:

  "type": "model",
  "authority-id": "<your account id>",
  "brand-id": "<your account id>",
  "series": "16",
  "model": "my-pi3",
  "architecture": "armhf",
  "gadget": "pi3",
  "kernel": "pi2-kernel",
  "timestamp": "<timestamp>"
  • authority-id, brand-id are your Ubuntu SSO account ID. See your account page, in the Account-Id field.
  • series: the Ubuntu Core series in use
  • model: a free form lower-case name for your target device.
  • architecture: the architecture of the device you are building the image for
  • gadget and kernel refer to snaps already existing in the store or in the current directory
  • timestamp is a valid timestamp you need to generate using the date -Iseconds --utc command. The timestamp must be later than when the key that signs the model was registered.
  • required-snaps: you can optionally add a list of required snaps that will be unremovable and will be downloaded from the store or locally if they exist in the current directory

Note: There are additional requirements when the image targets a Brand Store. Use your Brand SSO Account's account-id in the the authority-id and brand-id fields. Also add a store key whose value is your Brand store-id.

2. Sign your model assertion

Now you have to sign the model assertion with a key, by piping your JSON model through the snap sign -k <key name> command and outputting a model file, the actual assertion document you will use to build your image.

Note: If the model is for a Brand Store, the key must be registered by the Brand SSO Account.

cat pi3-model.json | snap sign -k default &> pi3.model

This command will ask you for the password you used on key creation to secure the key.

3. Build the image

You can now create your image with the ubuntu-image tool.

To install it, run:

snap install --beta --devmode ubuntu-image

Then, create the image:

sudo ubuntu-image -c beta -O pi3-test pi3.model


  • -c: the channel snaps are downloaded from
  • -O: a directory for generated files

You can include specific snaps pre-installed by default in the image by using the --extra-snaps argument. For example:

sudo ubuntu-image -c beta --extra-snaps rocketchat-server --extra-snaps nextcloud -o pi3-test.img pi3.model

Note: The --extra-snaps argument takes either a snap name accessible from the store or a local path to a built snap.

4. Your image is ready

You can use a tool like dd to write the image to an SDcard and boot your device.

sudo dd if=pi3-test.img of=/dev/sdb bs=32M

First boot tips

  • On the first boot you have to sign in with a valid Store account to make use of the device.
  • console-conf will download the SSH key registered with your Store account and configure it so you can log into the device via ssh <account name>@<device address> without a password.
  • There is no default ubuntu user on these images, but you can run sudo passwd <account name> to set a password in case you need a local console login.

Known problems and limitations:

  • You need a monitor or a serial cable plugged to the device to be able to go through the first use setup process handled by console-conf.