image-garden make and the other commands

the command line for users

image-garden make runs GNU make with image-garden.mk, in .image-garden/ when that directory exists, and builds the system you name. This deck shows what it prints, how to list systems and preview a build, and where the files go; the reference below covers every command, make goal and environment variable.

On the map: runtime

▶ Watch this deck — 7 scenes, ~5 min

Worth seeing first

Part of journeys

01 One command for every system

IMAGE-GARDEN MAKE $ image-garden make FILE $ image-garden make ubuntu-cloud-24.04.x86_64.run a launcher that boots it $ image-garden make ubuntu-cloud-24.04.x86_64.qcow2 just the prepared disk the snap a native package the container the same command in every install
image-garden make followed by a file name: SYSTEM.run gives a launcher that boots the system, SYSTEM.qcow2 gives only the prepared disk; the command is the same in the snap, a native package and the container

image-garden make SYSTEM.run builds a launcher; SYSTEM.qcow2 builds only the prepared disk. The command is the same in every install.

Most of what you do with image-garden starts with one command: image-garden make, followed by the name of a file you want. Ask for a system's .run file and you get a launcher that boots it. Ask for its .qcow2 and you get just the prepared disk. It's the same command whether you installed the snap, a native package, or you're inside the container. This deck shows what that command really runs, what it prints while it works, how to list the systems, how to preview a build without doing it, and where the files end up.

Details and sources

Details

Read more

02 GNU make underneath

UNDERNEATH $ image-garden make -n ubuntu-cloud-24.04.x86_64.run kvm_check /dev/kvm exists, not writable: a large WARNING without KVM: emulated, slow exec make --warn-undefined-variables \ GARDEN_ITSELF=… GARDEN_PROJECT_DIR=… \ -f …/image-garden.mk -C <.image-garden or .> \ "$@" your goal, -n and variables go straight to make
image-garden make first checks /dev/kvm and warns when it exists but is not writable, since machines are then emulated; then it runs make -f image-garden.mk with GARDEN_ITSELF and GARDEN_PROJECT_DIR and passes the goal, options and variables through

image-garden make checks /dev/kvm, then runs make -f image-garden.mk with GARDEN_ITSELF and GARDEN_PROJECT_DIR, passing your arguments on.

Under the hood, image-garden make is GNU make with a makefile chosen for you. First the script checks KVM: if /dev/kvm exists but you can't write to it, it prints a large warning and tells you how to fix it, because without KVM every machine is emulated and slow. Then it runs make on image-garden.mk, the rules for every system, and tells make where image-garden itself lives, so recipes can call it back for downloads. Everything else you type goes straight to make: the goal, options such as -n, and variables.

Details and sources

Details

  • kvm_check prints a large WARNING when /dev/kvm exists but is not writable, with advice: sudo usermod -aG kvm $LOGNAME, or in CI ($CI set) sudo chmod 666 /dev/kvm. It does not stop the build (image-garden:670-709).
  • image-garden make runs exec make --warn-undefined-variables GARDEN_ITSELF=… GARDEN_PROJECT_DIR=… -f $GARDEN_INCLUDE/image-garden.mk -C <dir> "$@", where <dir> is .image-garden when it exists (image-garden:982-993).
  • The makefile ends by including the project's .image-garden.mk, if there is one (999-local.mk:4-5).
  • Variables such as QEMU_MEM_SIZE=4096 are make variables: pass them on the command line or set them in .image-garden.mk (README.md:882-888).

03 What it prints while it works

WHAT IT PRINTS | Download and verify base image for ubuntu-cl Sat, 21 Nov 2026 10:02:17 +0000 | | Prepare writable qcow2 for ubuntu-cloud-24.0 Sat, 21 Nov 2026 10:04:51 +0000 | | Provision ubuntu-cloud-24.04.x86_64 Sat, 21 Nov 2026 10:04:51 +0000 | … the guest's serial console scrolls past … also in SYSTEM.qcow2.log | Generate launcher script for ubuntu-cloud-24 Sat, 21 Nov 2026 10:07:33 +0000 | each title is cut to 44 characters; the times are an example $ image-garden make ubuntu-cloud-24.04.x86_64.run nothing to do: all up to date
make prints four banners with the time, the title cut to 44 characters: download and verify the base image, prepare the writable qcow2, provision, with the serial console also saved to SYSTEM.qcow2.log, and generate the launcher script; a second run has nothing to do

Banners: Download and verify base image, Prepare writable qcow2, Provision, Generate launcher script. The console of the provisioning boot is kept in SYSTEM.qcow2.log.

While it works, make prints a banner for each big step, with the time. First it downloads and verifies the base image. Then it prepares the writable qcow2 on top of it, and provisions it. Provisioning is the long one: the guest's serial console scrolls past as cloud-init runs, and the same text goes into a log file next to the disk. When the guest powers itself off, make generates the launcher script and finishes. Run the same command again and make has nothing to do, because every file is up to date.

Details and sources

Details

  • The banners come from GARDEN_LOG_SECTION: a border of =, then | %-44.44s %31.31s | with the title and date -u '+%a, %d %b %Y %H:%M:%S %z', so titles longer than 44 characters are cut (000-garden.mk:32-36). In CI ($CI set) an extra empty row is printed so log viewers keep the gap.
  • The titles: "Download and verify base image for SYSTEM" (rulegen.py:498-514), "Prepare writable qcow2 for SYSTEM", "Provision SYSTEM" and "Generate launcher script for SYSTEM" (rulegen.py:593-610).
  • The provisioning boot's output is piped through tee SYSTEM.qcow2.log (rulegen.py:609).
  • The launcher is made after the disk because SYSTEM.run has the disk as an order-only prerequisite (rulegen.py:593-596).
  • The times on the slide are an example.

04 Finding a system to make

FINDING A NAME $ image-garden make list-systems almalinux-cloud-10.x86_64 … ubuntu-cloud-24.04.x86_64 ubuntu-cloud-24.04@web.x86_64 your own instances too $ image-garden make Usage: image-garden make <SYSTEM>.{run,qcow2} image-garden make fedora-cloud-44.x86_64.run (picked at random) $ image-garden Usage: image-garden make GOAL | allocate | rebase | discard | ps | version | news | download…
Three ways to find a name: image-garden make list-systems prints every system with its architecture, image-garden make with no goal prints help with a random example, and image-garden with no arguments prints the usage of every command

image-garden make list-systems lists every system; image-garden make prints help with a random example; image-garden prints the usage of every command.

Which names can you ask for? image-garden make list-systems prints every system it knows, one per line, with its architecture, including the named instances your own project defines. Run image-garden make with no goal at all and you get a short help text, with a system picked at random as an example. And image-garden with no arguments prints the usage of every other command: allocate, discard, ps, rebase, version, news and the download helpers. Between the three you rarely need to guess a name.

Details and sources

Details

05 Look before you build

LOOK BEFORE YOU BUILD $ image-garden make -n ubuntu-cloud-24.04.x86_64.run image-garden download-with-sha256sums https://cloud-images.ubuntu.com/… qemu-img create -f qcow2 -b …/ubuntu-cloud-24.04.x86_64.qcow2 -F qcow2 … 64G qemu-system-x86_64 -cpu max -machine q35,… -m 2048 … printed, not run the exact QEMU command of the provisioning boot $ image-garden make -B ubuntu-cloud-24.04.x86_64.run makes it all again a complete download is kept: it is fetched only when missing
With -n or --dry-run make prints the commands it would run, such as the qemu-img create and the qemu-system-x86_64 command of the provisioning boot, without running them; -B makes everything again, but a complete download is not fetched again

image-garden make -n SYSTEM.run shows the commands without running them. -B rebuilds everything except complete downloads.

Before you spend ten minutes on a build, you can look at it first. Add -n, or --dry-run, and make prints every command it would run, without running any of them. That's the easiest way to learn the exact QEMU command of the provisioning boot, or to see which download a system needs. Minus capital B goes the other way: it makes everything again, even what's up to date. A download that's already complete isn't fetched twice, though, because an image is only downloaded when it isn't there.

Details and sources

Details

  • -n displays commands without executing them; -B forces a rebuild, but a complete download is not repeated (README.md:514-519). -n and --dry-run are the same GNU make option.
  • A complete download is skipped because the downloaded file is kept in the cache and the download helpers only fetch what is missing or does not match its checksum (image-garden:480-559).
  • The QEMU command on the slide is abridged; -n prints it in full.

06 Where the files go

WHERE THE FILES GO your-project/ ubuntu-cloud-24.04.x86_64.qcow2 … .qcow2.log .seed.iso … .efi-code.qcow2 .efi-vars.qcow2 … .user-data .meta-data ubuntu-cloud-24.04.x86_64.run about eight files per system your-project/ .image-garden/ all of those files src/ tests/ spread.yaml out of your way ~/.cache/image-garden/dl/ downloads stay in the shared cache your-project/.image-garden.mk read by make; editing it rebuilds images
By default the disk, log, seed, firmware copies and launcher land in the current directory; with a .image-garden directory they go inside it; downloads stay in the cache; a .image-garden.mk in the project is read by make and editing it rebuilds images

With a .image-garden/ directory every generated file goes there. .image-garden.mk is read by make, and changing it rebuilds the images that depend on it.

And where do the files go? By default, into the directory you're in: the disk, its log, the seed, the firmware copies and the launcher, about eight files for each system. Create a directory called .image-garden in your project, and image-garden make switches into it, so all of that stays out of your way. Downloads never go there; they stay in the shared cache. And if your project has a .image-garden.mk file, make reads it as well, and editing it marks the system's images as out of date.

Details and sources

Details

07 Where to go from here

ROADS image-garden make The .run script boot what you built The serial console why the TTY acts oddly The target chain every file, in order allocate in the background, with SSH Where files live Your own changes .image-garden.mk What runs where every system to name
Seven roads from image-garden make: the .run script, the serial console, the target chain, allocate, where files live, your own changes in .image-garden.mk and the support matrix

Next: the .run script, the serial console, the target chain, allocate, where files live, .image-garden.mk and the support matrix.

That's image-garden make: GNU make on the rules for every system, a banner for each step, a list of systems, a dry run when you want one, and a tidy directory for the results. Next, boot what you built with its .run script, and read about the serial console it gives you. The target chain deck goes through every file make builds, in order. Allocate starts a machine in the background with SSH. And to change what a system gets, write a .image-garden.mk for your project.

Details and sources

Read more

Basis of the statements on this page

Read in the image-garden source at the commit in garden.commit ("code"): the image-garden script, mk/*.mk, rulegen.py, the README and the man page image-garden.1. Where the documentation and the code differ, this page follows the code and says so. Nothing was run for this page.

Commands

CommandWhat it does
image-garden make [MAKE-OPTIONS] [GOAL…]checks /dev/kvm, then runs GNU make on image-garden.mk, in .image-garden/ when it exists (image-garden:982-993)
image-garden allocate [-p PORT] [--premade] [--nice] [--spread] SYSTEM.ARCH [QEMU-OPTION…]makes the system unless --premade, starts it in the background with -snapshot and SSH on a local port, prints the address (image-garden:996-1219)
image-garden discard ADDRESSstops the machine at localhost:PORT and removes its pid file and TPM state copy (image-garden:1221-1274)
image-garden discard -astops every allocated machine
image-garden ps [--all] [--stale]lists allocated machines: address, PID, memory and system; --stale those whose QEMU is gone, --all every entry (image-garden:1276-1358)
image-garden rebase SYSTEM.ARCHpoints a prepared disk's backing file at the matching download in $GARDEN_DL_DIR, with qemu-img rebase -u, so the old download need not exist; takes the system name or its .qcow2 file; fails if there is no matching download (image-garden:943-980)
image-garden version, --versionprints the version (image-garden:909-911)
image-garden news [N]prints the last N releases from NEWS, then the snap's or the container's notes; N defaults to 1 (image-garden:912-942)
image-garden download-with-sha512sums URL [SUMS-URL] [DIR] [FILENAME]downloads and checks against a SHA512SUMS list; the list defaults to SHA512SUMS next to the image, DIR to $GARDEN_DL_DIR (image-garden:358-362)
image-garden download-with-sha256sums URL [SUMS-URL] [DIR] [FILENAME]the same with a SHA256SUMS list (image-garden:460-464)
image-garden download-with-sha256sum URL SHA256 [DIR] [FILENAME]the same with one known hash, which is required (image-garden:562-577)
image-garden download URL [DIR] [FILENAME]downloads without a checksum (image-garden:627-630)
image-garden, -h, --helpprints the usage (image-garden:889-908)

Options of allocate (README.md:404-424):

OptionMeaning
-p PORTtry this port first; a random free port in 5000-9999 otherwise
--premadedo not make the system, use the images that are there
--nicerun QEMU with nice; on by default in x11 and wayland sessions
--spreadprint <ADDRESS localhost:PORT> and <FATAL …> for spread, and wait for SSH first

Make goals

GoalWhat it makes (README.md:506-577)
helpthe default: usage and a random example
list-systemsevery system, with its architecture, including named instances
SYSTEM.ARCH.runthe launcher, with everything it needs
SYSTEM.ARCH.qcow2only the prepared disk
allevery system of the host's architecture
fetchevery download of the host's architecture, for working offline
cleanremoves generated images, logs and support files here; keeps downloads
distcleanclean, and removes the downloads from the cache

Useful make options: -n (print, do not run), -B (make again; complete downloads are kept), -j (several systems at once).

The .run script

UseEffect
./SYSTEM.runboots in the foreground on the serial console; changes are kept
./SYSTEM.run -snapshotthe same, but changes are thrown away when QEMU exits
./SYSTEM.run --queryprints vm.memory_mb and system.users.N.username and .password, then exits (010-qemu.mk:57-92)
./SYSTEM.run ARGS…any other arguments are added to the QEMU command (010-qemu-x86_64.mk:105)
./SYSTEM.run of a +tpm systemmust be run from its own directory, next to SYSTEM.tpm/

Environment variables

VariableUsed byMeaning
XDG_CACHE_HOMEallbase of the cache; default $HOME/.cache
GARDEN_CACHE_DIRallthe cache; default $XDG_CACHE_HOME/image-garden, in the snap $SNAP_USER_COMMON/cache (image-garden:20-29)
GARDEN_DL_DIRalldownloaded images; default $GARDEN_CACHE_DIR/dl
PKGPROXY_URLmake, downloadsa pkgproxy for guests and image downloads
GARDEN_DL_PKGPROXYdownloadsa pkgproxy for image downloads alone, http://host:port or unix:/path; set empty to turn downloads through pkgproxy off (image-garden:31-58)
XDG_RUNTIME_DIRallocate, discard, pspid files, ports and locks, under image-garden/; default /run (image-garden:60-73)
QEMU_SNAPSHOT_OPTIONallocatedefault -snapshot; set empty to keep changes (image-garden:1154)
GARDEN_SSH_WAIT_TIMEOUTallocate --spreadseconds to wait for SSH; default 600 (image-garden:1173)
GARDEN_MEMORY_RESERVEallocateMB kept for the host in the memory check; default 2048 in x11 and wayland sessions, 1024 otherwise (image-garden:733-745)
XDG_SESSION_TYPEallocatex11 or wayland turn on nice and the larger reserve
GARDEN_TPM_RUN_DIR.run of a +tpm systemwhere swtpm runs; allocate sets it per port (image-garden:1110-1111)
QEMU_MEM_OPTION.rundefault -m 2048 (010-qemu.mk:9, 010-qemu.mk:12)
QEMU_SMP_OPTION.rundefault -smp N: 4 on the host's own architecture, 1 otherwise
QEMU_DISPLAY_OPTION.rundefault -nographic; allocate uses -display none (010-qemu.mk:13, image-garden:1105)
QEMU_BOOT_FIRMWARE_OPTION, QEMU_STORAGE_OPTION, QEMU_RNG_OPTION, QEMU_NET_OPTION, QEMU_TPM_OPTION, QEMU_ACCEL_MACHINE_PROP.runreplace one part of the QEMU command each (010-qemu-x86_64.mk:72-80)
QEMU_NETDEV_USER_EXTRA.runappended to -netdev user; allocate uses it for the SSH port forward (image-garden:1107)
QEMU_MEM_SIZE, QEMU_IMG_SIZE, QEMU_SMP_<ARCH>, QEMU_CPU_<ARCH>makememory, disk size, CPUs and CPU model baked into new launchers; pass on the make command line (README.md:882-899)
QEMU_SYSTEM_<ARCH>, QEMU_IMG, XORRISO, CURL, SWTPMmakethe tools to run (README.md:915-920)

The README and the man page list the .run variables, QEMU_NET_OPTION, QEMU_NETDEV_USER_EXTRA, QEMU_STORAGE_OPTION, QEMU_TPM_OPTION and QEMU_ACCEL_MACHINE_PROP among them (README.md:922-947, image-garden.1:638-679); the scripts read them as listed (010-qemu-x86_64.mk:72-80).

Roads from here

SYSTEMS · distributions

RUNTIME · make rules and the CLI

FIRST BOOT · cloud-init changes