README
¶
ubuntu-image: build Ubuntu images
ubuntu-image is a tool used for generating bootable images. You can use it to build Ubuntu images such as:
-
Snap-based Ubuntu Core images from model assertions
-
Classical preinstalled Ubuntu images using image definitions
The future versions of this tool will be more generalized, allowing users to build a wider range of Ubuntu images, including ISO/installer.
Getting started
Requirements
-
Ubuntu 20.04 (Focal Fossa) or newer (recommended: Ubuntu 24.04 (Noble Numbat))
-
Ability to install snaps (SnapStore: ubuntu-image)
Quickstart
See Build your first Ubuntu Core image for instructions on how to use ubuntu-image to build an Ubuntu core image on a Raspberry Pi.
[!IMPORTANT]
ubuntu-imagerequires elevated permissions. Run it with root privileges or usingsudo.
Building images
ubuntu-image offers two basic sub-commands for building snap-based and classical images.
Building snap-based images
To build a snap-based image with ubuntu-image, you need a model assertion. A model assertion is a YAML file that describes a particular combination of core, kernel, and gadget snaps, along with other declarations, signed with a digital signature asserting its authenticity. The ubuntu-image command only requires the path to this model assertion to build snap-based images.
To build snap-based images with ubuntu-image, use the following command:
ubuntu-image snap model.assertion
See Build your first Ubuntu Core image for more information on building snap-based images using ubuntu-image. To build an image with custom snaps, see Build an image with custom snaps.
Building classical images
Classical images are built from image definitions, which are YAML files. The image definition YAML file specifies the various configurations required to build a classical image, including the path to the gadget.yaml file. See Image Definition for the detailed specification of what is supported in the image definition YAML file.
To build classical images with ubuntu-image, use the following command:
ubuntu-image classic image_definition.yaml
Building and testing ubuntu-image
See Contributing to ubuntu-image for instructions on how to set up, build, and test ubuntu-image in development mode.
License
The ubuntu-image project is licensed under GNU General Public License v3.0.
Contributing to ubuntu-image
To learn how to contribute to the ubuntu-image project, see Contributing to ubuntu-image.
Project details
- Project home: https://github.com/Canonical/ubuntu-image
- Report bugs at: https://bugs.launchpad.net/ubuntu-image
- Git clone: https://github.com/Canonical/ubuntu-image.git
- Reference page:
ubuntu-imagesyntax and options - Building a gadget snap: Building a gadget snap
- Gadget tree: pc-gadget
gadget.yamlspecification: Gadget snaps
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
ubuntu-image
Package ubuntu-image provides a tool used for generating bootable images.
|
Package ubuntu-image provides a tool used for generating bootable images. |
|
internal
|
|
|
commands
Package commands defines structures and variables used to parse command line input
|
Package commands defines structures and variables used to parse command line input |
|
imagedefinition
Package imagedefinition provides the structure for the image definition that will be parsed from a YAML file.
|
Package imagedefinition provides the structure for the image definition that will be parsed from a YAML file. |
|
ppa
Package ppa manages Private Package Archives sources list.
|
Package ppa manages Private Package Archives sources list. |
|
statemachine
Package statemachine provides the functions and structs to set up and execute a state machine based ubuntu-image build
|
Package statemachine provides the functions and structs to set up and execute a state machine based ubuntu-image build |
|
testhelper
Package testhelper provides helpers to ease mocking functions and methods provided by packages such as os or http.
|
Package testhelper provides helpers to ease mocking functions and methods provided by packages such as os or http. |