image-garden(1) General Commands Manual (prm) image-garden(1)

image-garden — construct and operate test virtual machines

image-garden make [-n] [GOAL]

image-garden allocate -p PORT [--premade] [--nice] [--spread] SYSTEM.ARCH

image-garden rebase SYSTEM.ARCH

image-garden discard [-a | ADDRESS]

image-garden ps [--all [--stale]]

image-garden version

image-garden news N

image-garden download-with-sha512sums URL [SHA512SUMS_URL [DIRECTORY_PREFIX [FILENAME]]]

image-garden download-with-sha256sums URL [SHA256SUMS_URL [DIRECTORY_PREFIX [FILENAME]]]

image-garden download-with-sha256sum URL [SHA256SUM [DIRECTORY_PREFIX [FILENAME]]]

image-garden download URL [DIRECTORY_PREFIX [FILENAME]]

image-garden downloads, initializes and optionally operates virtual machine images for popular operating systems. All the systems are designed for and come configured with , usually matching the name of the system.

Options recognized by image-garden make

Display commands instead of executing them. This option is useful for learning how to make individual disk images.

When using download helper commands with an explicit FILENAME, the local cached file may have a different name than basename of URL. For checksum-list based helpers download-with-sha256sums and download-with-sha512sums, checksum verification supports this mode and validates the downloaded local file against checksum entries keyed by upstream filename.

Options recognized by image-garden allocate

PORT
Attempt using given port when allocating a machine. This is useful when working with a one-off system. Using a fixed port is more friendly to shell history searches.
Assume presence of pre-made disk images and do not re-generate them even if they are out-of-date. This option is useful for ensuring that CI/CD jobs do not re-build disk images even if timestamps would suggest they should.
Wrap execution of virtual machines with nice, so that it does not compete for CPU with other applications. This is implicitly set when XDG_SESSION_TYPE is either or .
Emit output in spread protocol form, on success and on failure. Without this option, image-garden allocate prints plain "localhost:PORT" output.

Options recognized by image-garden discard

Discard all allocated virtual machines at once.

Options recognized by image-garden ps

Show all pidfiles found in the per-user runtime directory and mark entries that are stale or malformed with an explanatory suffix.
Show only pidfiles that are stale or malformed (do not list running entries).

The image-garden make sub-command allows building one or more corresponding to virtual machine images and their support files.

The following goals are documented. Note that and are placeholders for CPU architecture as named by the Linux kernel and standardized distribution name, respectively. Please see the table for a complete list of valid SYSTEM-ARCH combinations.

help
Display help message specific to the set of make rules contained within image-garden
all
Build all of the images for the native CPU architecture.
fetch
Fetch all the base cloud images or installers, so that further work can be done offline. The only exception is installation if packages described by per-project cloud-init profiles.
clean
Remove all the generated disk images from the current directory.
distclean
Remove all the base cloud images and installer images from the per-user cache directory.
$SYSTEM.$ARCH.qcow2
disk image of operating system for CPU architecture . Cloud disks contain internal reference to base image stored in per-user cache directory. Both files are required at runtime.
$SYSTEM.$ARCH.qcow2.log
Serial console output collected during first boot of the machine.
$SYSTEM.$ARCH.run
Shell script for running the virtual machine. This script supports extensive customization through environment variables and command line arguments. Command line arguments are passed directly to image-garden qemu-system-$ARCH . Recognized environment variables are described in a dedicated section below.
$SYSTEM.$ARCH.efi-code.img
Symbolic link to efi-code.$ARCH.img.
$SYSTEM.$ARCH.efi-vars.img
Disk image with current state of the boot firmware corresponding to $SYSTEM.$ARCH.qcow2.
$SYSTEM.$ARCH.seed.iso
ISO 9660 disk image with cloud-init files used during first boot.
$SYSTEM.$ARCH.user-data
Text of the cloud-init user data. This file exists briefly as a prerequisite for $SYSTEM.$ARCH.seed.iso.
$SYSTEM.$ARCH.meta-data
Text of the cloud-init meta data. This file exists briefly as a prerequisite for $SYSTEM.$ARCH.seed.iso.
efi-code.riscv64.img
Disk image of EFI firmware for riscv64 CPU architecture.
efi-vars.riscv64.img
Disk image of with the unmodified state of EFI firmware for the riscv64 CPU architecture.
efi-code.aarch64.img
Disk image of EFI firmware for aarch64 CPU architecture.
efi-vars.aarch64.img
Disk image of with the unmodified state of EFI firmware for the aarch64 CPU architecture.
efi-code.x86_64.img
Disk image of EFI firmware for the x86_64 CPU architecture.
efi-vars.x86_64.img
Disk image of with the unmodified state of EFI firmware for the x86_64 CPU architecture.

Systems are identifiers for a particular operating system, variant, release and CPU architecture. The following list contains all the systems recognized by image-garden.

almalinux-cloud-{8,9,10}
Alma Linux cloud images.
alpine-cloud-3
Alpine Linux cloud image.
amazonlinux-cloud-{2,2023}
Amazon Linux cloud images.
archlinux-cloud
Arch Linux cloud image. This system is only supported on the x86_64 CPU architecture.
centos-cloud-{9,10}
CentOS cloud images (usually CentOS stream).
debian-cloud-{10,11,12,13,sid}
Debian cloud images.
fedora-cloud-{38,39,40,41,42,43,44}
Fedora cloud images. Fedora 42, only, is also supported on the riscv64 CPU architecture. Fedora 42, 43 and 44 are also supported on the s390x CPU architecture.
opensuse-cloud-{15.4,15.5,15.16,tumbleweed}
openSUSE cloud images.
oracle-cloud-{7,8,9}
Oracle Linux cloud images. Oracle Linux 7 is only supported on the x86_64 CPU architecture.
rocky-cloud-{8,9}
Rocky Linux cloud images.
ubuntu-cloud-{14,16,18,20,22,24,26}.04
Ubuntu Long Term Support (LTS) cloud images.
ubuntu-cloud-{16.10,17.04,17.10,18.10,19.04,19.10,20.10,21.04,21.10,22.10,23.04,23.10,24.10}
Ubuntu EOL interim cloud images for x86_64. These images are fetched from archived release locations. Their cloud-init profile rewrites apt sources to to keep package operations functional after EOL. For consistency with cloud-init behavior, this apt source rewrite is currently applied to EOL Ubuntu interim releases from 16.10 through 24.10.
ubuntu-cloud-{25.04,25.10}
Ubuntu development releases cloud images. Ubuntu 24.04, 25.04 and 25.10 are also supported for riscv64 CPU architecture. Ubuntu 18.04, 20.04, 22.04, 24.04, 25.04, 25.10 and 26.04 are also supported for s390x CPU architecture. Ubuntu 14.04, 16.04, 18.04, 20.04, 22.04, 24.04, 25.04, 25.10 and 26.04 are also supported for CPU architecture.
ubuntu-core-{16,18,20,22,22+dangerous,24,24+dangerous,26,26+dangerous}
Ubuntu Core images. Core 16, 18 and 20 are only supported on the x86_64 CPU architecture. The dangerous variants are only supported on the x86_64 CPU architecture.

.image-garden
Sub-directory containing all image, log and lock files. If this directory does not exist then all such files are placed in the directory where image-garden is invoked from.
.image-garden.mk
Makefile implicitly included by image-garden make. This file is designed for defining cloud-init user-data templates with project-specific build and test dependencies.
$HOME/.cache/image-garden/dl
Directory with downloaded, unmodified virtual machine images. The files are organized into sub-directories specific to each distribution. Inside symbolic links provide an unified naming scheme regardless of the naming scheme used by a particular distributor.

Environment variables are split into sections to indicate which of the sub-commands uses them.

Directory with per-user cache files that may be safely deleted. According to the specification the default value is "$HOME/.cache".
Directory with non-essential files that can be reused across projects. The default value is "$XDG_CACHE_HOME/image-garden", except when used as a snap where the default value is "$SNAP_USER_COMMON/cache".
Directory where downloaded operating system images are stored. Those images may be sizable so care needs to be taken to avoid using excessive amount of disk space. All the images stored here are used in read-only mode and are automatically shared by different project developed by the same user. The default value is "$GARDEN_CACHE_DIR/dl".
A list of environment variables to set before invoking qemu. This was introduced to allow expressing that a given system cannot boot with virtio disk and needs to use SCSI disks instead.
Amount of memory, in megabytes, to provide to each virtual machine. This value is copied into the generated scripts. The default value is "2048", for 2GB of runtime memory. Not to be confused with similarly-named QEMU_MEM_OPTION.
Size of the virtual disk image created by qemu-img(1) when invoked from image-garden. The default value is "64G". Note that images use a format with internal representation of sparse areas. The required disk space is much smaller than this size.
The number of virtual CPU cores for virtual machines emulating the x86_64 CPU architecture. The default value is "4" when the CPU architecture of the host and the guest are the same or "1" otherwise. Not to be confused with similarly-named QEMU_SMP_OPTION.
The number of virtual CPU cores for virtual machines emulating the aarch64 CPU architecture. The default value is "4" when the CPU architecture of the host and the guest are the same or "1" otherwise. Not to be confused with similarly-named QEMU_SMP_OPTION.
The number of virtual CPU cores for virtual machines emulating the riscv64 CPU architecture. The default value is "4" when the CPU architecture of the host and the guest are the same or "1" otherwise. Not to be confused with similarly-named QEMU_SMP_OPTION.
Full path of the qemu-system-x86_64 program to use instead of the one found on PATH.
Full path of the qemu-system-aarch64 program to use instead of the one found on PATH.
Full path of the qemu-system-riscv64 program to use instead of the one found on PATH.
Virtual CPU type to use for systems using the riscv64 CPU architecture. The default value is max.
Virtual CPU type to use for systems using the x86_64 CPU architecture. The default value is max.
Virtual CPU type to use for systems using the aarch64 CPU architecture. The default value is max. The and systems use the value .
Full path of the qemu-img program to use instead of the one found on PATH.
Full path of the xorriso program to use instead of the one found on PATH.
Full path of the wget program to use instead of the one found on PATH.

Directory with per-user runtime files that do not persist across reboots. According to the specification the default value is "/run/user/$UID". The image-garden program, when used as a back-end for the spread(1) test system uses this directory to keep track of running virtual machines and their TCP port numbers.
Overrides the in-memory snapshot option. Set this to the empty string to allocate a machine that persists all changes on disk.
Amount of memory (in megabytes) to reserve for the host system when checking if there is sufficient memory available for virtual machine allocation. This value is used by the allocate command to warn users if VM memory requirements may exceed available resources.

When unset, the default value depends on XDG_SESSION_TYPE: 2048MB is reserved for graphical sessions (x11 or wayland), and 1024MB is reserved for other session types (including headless servers).

The memory check accounts for QEMU overhead by applying a 1.5x multiplier to the VM memory requirement, then adding the reserve. A warning is issued if:

VM_memory × 1.5 + GARDEN_MEMORY_RESERVE > MemAvailable

For example, a VM requesting 2048MB with 1024MB reserve requires 2048 × 1.5 + 1024 = 4096MB of available system memory.

Example values: "512" (minimal reserve), "3072" (extra reserve for memory-intensive desktop).

Discard one or more virtual machines.

When invoked with -a, discard all allocated virtual machines. When invoked with an ADDRESS argument, discard the specific machine at that address. The address format is "localhost:PORT" where PORT is the forwarded SSH port allocated by image-garden allocate.

Discard removes the pidfile and metadata file for the machine, then kills its process. This is useful for cleanup after testing sessions or in CI/CD environments.

List running virtual machines recorded in the per-user runtime directory. The command reads pidfiles named `port.<PORT>.pid` from `$XDG_RUNTIME_DIR/image-garden`, validates that the PIDs are numeric and correspond to running processes, and prints a human-friendly table with `ADDRESS`, `PID`, `RSS(MB)`, and `SYSTEM` columns.

The `SYSTEM` column displays the system name that was allocated. For virtual machines allocated before this feature was added, a dash (`-`) is displayed instead.

See the EXAMPLES section for sample output.

Notes: use `--all` to show stale or malformed pidfiles.

The following environment variables are used by generated .run scripts.

Memory configuration options to pass to qemu. Example value is "-m 1024".
CPU topology options to pass to qemu. When unset the default value is "-smp $QEMU_SMP_$(uname -m)". Example value is "-smp $(nproc)".
Graphical display options to pass to qemu. When unset the default value is "-nographic". Example value is "-display gtk".
Boot firmware options to pass to qemu. The default value depends on the requirement of the booted system. For systems booting with EFI a pair of "-drive pflash" arguments is used for representing EFI code and EFI variables. For systems booting with legacy BIOS no options are provided.
Random-number configuration options to pass to qemu. When unset the default value is "-device virtio-rng-pci"
 
 
Network configuration options to pass to qemu. When unset the default value is "-netdev user,id=netdev0${QEMU_NETDEV_USER_EXTRA:-} -device virtio-net-pci,netdev=netdev0,id=net0" For x86_64 and aarch64 CPU architectures the value also includes the suffix. "-smbios type=41,designation=Virtual-LAN,instance=1,kind=ethernet,pcidev=net0"

To create a bootable image of cloud variant of Debian 13 (trixie) for x86_64 architecture run:

image-garden make debian-cloud-13.x86_64.run

To use image-garden together with spread(1)

put the following snippet into your spread.yaml file. Note that using allows image-garden to automatically perform the equivalent of calling spread shell functions , or .

backends:
  garden:
    type: adhoc
    allocate: exec image-garden allocate --spread "$SPREAD_SYSTEM"."$(uname -m)"
    discard: exec image-garden discard "$SPREAD_SYSTEM_ADDRESS"
    systems:
      - debian-cloud-13:
          username: debian
          password: debian

To customize the virtual machine to a particular project create a .image-garden.mk file in the root of the project and define one or more cloud-init user-data templates which contain list of packages to install or commands to run. Make sure to include the default template that is essential for image-garden operation. You can assume that the default template ends with a section that runs one or more commands and append your commands as a YAML list. Other cloud-init features must be used explicitly.

A single base system can be instantiated multiple times with distinct disk images, cloud-init profiles, and hostnames using the macro in .image-garden.mk:

$(eval $(call define-instance,ubuntu-cloud-24.04,webserver))
$(eval $(call define-instance,ubuntu-cloud-24.04.x86_64,database))

The architecture suffix can be omitted; $(GARDEN_ARCH) is used automatically. Each instance creates a new system base@name.arch with its own .qcow2, .run, .meta-data, .user-data, and .seed.iso files. The instance inherits the base system's boot type (EFI/BIOS/platform) and the hostname follows the base-release-name convention.

Templates are looked up in the following order (most specific first):

  1. GROUP_RELEASE@instance_CLOUD_INIT_USER_DATA_TEMPLATE (e.g. UBUNTU_24.04@webserver_CLOUD_INIT_USER_DATA_TEMPLATE)
  2. GROUP@instance_CLOUD_INIT_USER_DATA_TEMPLATE (e.g. UBUNTU@webserver_CLOUD_INIT_USER_DATA_TEMPLATE)
  3. GROUP_RELEASE_CLOUD_INIT_USER_DATA_TEMPLATE (e.g. DEBIAN_13_CLOUD_INIT_USER_DATA_TEMPLATE)
  4. GROUP_CLOUD_INIT_USER_DATA_TEMPLATE (e.g. UBUNTU_CLOUD_INIT_USER_DATA_TEMPLATE)
  5. CLOUD_INIT_USER_DATA_TEMPLATE
# Per-release template for Debian 13 (Trixie).
define DEBIAN_13_CLOUD_INIT_USER_DATA_TEMPLATE
$(CLOUD_INIT_USER_DATA_TEMPLATE)
packages:
- build-essential
- libfoo-dev
endef
# Per-group template for all versions of Ubuntu.
define UBUNTU_CLOUD_INIT_USER_DATA_TEMPLATE
$(CLOUD_INIT_USER_DATA_TEMPLATE)
packages:
- build-essential
- libfoo-dev
endef
# Per-release-instance template.
define UBUNTU_24.04@webserver_CLOUD_INIT_USER_DATA_TEMPLATE
$(CLOUD_INIT_USER_DATA_TEMPLATE)
packages:
- nginx
endef
# Per-group-instance template (any Ubuntu release).
define UBUNTU@webserver_CLOUD_INIT_USER_DATA_TEMPLATE
$(CLOUD_INIT_USER_DATA_TEMPLATE)
packages:
- nginx
endef

image-garden ps
ADDRESS           PID       RSS(MB)   SYSTEM
localhost:5023    12345     640       ubuntu-cloud-24.04.x86_64

qemu(1)

Image garden was developed in stages throughout late 2023, with first commits appearing in early 2024.

Known bugs can be listed by looking at GitLab issues.

Zygmunt Krynicki <me@zygoon.pl>

January 19, 2026 image-garden 0.6.3