QEMU

QEMU is the fastest way to try Avocado OS. No hardware required — the virtual machine runs on your development machine.

Prerequisites

• macOS 10.12+ or Linux (Ubuntu 22.04+, Fedora 39+)
• 8 GB available disk space

Choose your setup

• macOS — install the Avocado CLI and Docker Desktop, or install Avocado Desktop, which bundles the build VM and toolchain — no Docker Desktop required.
• Linux — install Docker and either the Avocado CLI or Avocado Desktop, which ships as a deb, rpm, or pacman package. Docker is required either way on Linux: Desktop builds with the host's Docker rather than the VM it bundles on macOS. The pacman package is the exception to "either", since it links the Avocado CLI rather than bundling one, so install that too. For USB provisioning, add your distribution's usbip tools.
• Every shipping CLI build, with its size and SHA-256, is listed on Downloads.

Initialize

Create a new project targeting QEMU x86-64. The init command scaffolds an avocado.yaml with the default configuration for the target.

avocado init --target qemux86-64 qemux86-64
cd qemux86-64

Install

Install the SDK toolchain, extension dependencies, and runtime packages defined in avocado.yaml.

avocado install -f

This pulls the SDK container image and installs all required packages into their respective sysroots. The -f flag skips confirmation prompts.

Build

Build the system image — this compiles extensions and assembles the runtime.

avocado build

Troubleshooting a stale build volume

If avocado build fails during runtime build dev with a missing /etc/passwd (or /etc/shadow / /etc/group) under rootfs-work, the build volume is stale or half-populated. This happens when a previous install was interrupted, or when a project directory was deleted manually without first running avocado clean. The per-project Docker volume outlives the folder.

Reset the build state and rebuild:

avocado clean
avocado prune
avocado install -f
avocado build

avocado clean drops the current project's volume; avocado prune clears abandoned volumes left behind by deleted projects. Run both, since clean alone may not clear an abandoned volume that is shadowing the build.

Provision

Provision creates the bootable disk image for the dev runtime. Because QEMU is virtual, the provisioning artifacts are written to disk on your development machine rather than flashed to hardware.

avocado provision -r dev

Run

Boot the virtual machine using the SDK container's built-in QEMU:

avocado sdk run -iE vm dev

Log in as root with an empty password.

To verify the system is running:

uname -a
systemctl status

To shut down the VM:

poweroff

SSH access

Linux only

The --host-fwd flag is supported on Linux only.

To boot QEMU with SSH port forwarding:

avocado sdk run -iE vm dev --host-fwd "2222-:22"

Then from another terminal:

ssh -o StrictHostKeyChecking=no -p 2222 root@localhost