---
title: "QEMU"
---

# QEMU

Start an image the build wrote for QEMU with runqemu on the build host, its console in a terminal, and the guest in the Targets view for files, system views, debugging and runtime tests.

Images built for a QEMU machine (qemux86-64, qemuarm64) run with the Yocto Project's `runqemu` in the build environment on the build host.

**State:** modelled with runqemu of poky scarthgap 5.0.21 over OpenSSH 9.6p1 with QEMU 8.2.2 on qemuarm64: a `.qemuboot.conf` written from core-image-minimal's real datastore by qemuboot.bbclass's own code, a Linux 6.8 kernel and a BusyBox and Dropbear initramfs (a stand-in image); the guest in Targets after 11 to 27 seconds, the console both ways, the System view, Stop with nothing left, a dropped session stopping QEMU; a real `bitbake -c testimage` against it; the running app. Not run with an image built by BitBake, with tap networking or KVM, on qemux86-64, on Windows, against a real build server or on Wind River Linux. Debugging, perf and Valgrind on the QEMU guest were not run. `devtool runqemu` is not built.

## Start an image

1. Run **Start Image in QEMU...** from the command palette or the Targets view title.
2. Pick an image: the list holds each `.qemuboot.conf` in DEPLOY_DIR_IMAGE with its machine, root file systems, memory and KVM.
3. Pick the root file system and the options: **Snapshot** (writes go to a temporary file), **KVM**, and **Tap networking instead of slirp**.
4. The confirmation shows the build host, the build directory, the exact command and what needs root (tap needs `/dev/net/tun` and tap devices made once with `runqemu-gen-tapdevs`). The command is `runqemu <machine> <image>.qemuboot.conf nographic slirp snapshot`; the `runqemu <machine> <image>` form fails on scarthgap 5.0.21 with "IMAGE_LINK_NAME wasn't set".

![The runqemu options for an image: snapshot, KVM, and tap networking instead of slirp.](https://neuralinverse.com/docs-images/modules/embedded-linux/qemu-start-options.webp)

## The console and the guest

The serial console opens in a terminal both ways (**Show QEMU Console** brings it back). With slirp, the guest's SSH is reached through a port of this computer forwarded over the build host's SSH session, and the guest appears in Targets as root, with its host key kept for that instance only. Targets, the system views and runtime tests work on it; testimage runs through `simpleremote` at runqemu's forward with TEST_SERVER_IP `10.0.2.2`. The guest leaves Targets when QEMU stops.

## Stop it

**Stop QEMU...** asks first, then sends runqemu SIGTERM; its process group is killed after 15 seconds. A dropped session stops QEMU on the build host too.

## Agent tools

One read-only tool lists the images and runs; starting and stopping always ask first.

Next: [Update packages](https://neuralinverse.com/docs/modules/embedded-linux/update-packages/).