No description
  • C++ 98.6%
  • CMake 0.7%
  • Makefile 0.7%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-10-27 20:10:22 +08:00
src added 2026-10-27 20:10:22 +08:00
tests added 2026-10-27 20:10:22 +08:00
CMakeLists.txt added 2026-10-27 20:10:22 +08:00
Makefile added 2026-10-27 20:10:22 +08:00
README.md added 2026-10-27 20:10:22 +08:00

qemu-tui

A terminal front-end for managing QEMU virtual machines. Create, configure, start, inspect and snapshot VMs from a keyboard-driven interface — no XML, no daemon, no libvirt.

 qemu-tui  3 machines · 1 running                                    KVM available
┌─ Machines ────────────────────────┐┌─ Details ─────────────────────────────────┐
│   NAME             CPU      MEM   ││ debian12                        ● running │
│ ● debian12           4    4096M   ││                                           │
│ ○ alpine             2    1024M   ││ pid         31119                         │
│ ◐ win11              8    8192M   ││ uptime      01:24:07                      │
│                                   ││ host mem    4.2G                          │
│                                   ││ vnc         :3  (port 5903)               │
│                                   ││                                           │
│                                   ││ Hardware                                  │
│                                   ││ arch        x86_64 / q35                  │
│                                   ││ cpu         host  ×4  (kvm)               │
└───────────────────────────────────┘└───────────────────────────────────────────┘
 Ready. Press '?' for help.
 n new  e edit  x stop  p pause  c console  i disk  a snap  ? help  q quit

Building

Requires a C++17 compiler and ncurses. QEMU (qemu-system-*, qemu-img) must be installed at runtime.

make                # or: cmake -S . -B build && cmake --build build
make test           # run the unit tests
sudo make install   # installs to /usr/local/bin

Using it

Run qemu-tui with no arguments for the interface. Press n to create your first machine: give it a name, then on the ISO field press Enter to browse for an installer, and save with F10. The disk image is created for you. Press s to start it.

For a headless VM, press c to attach to its serial console; Ctrl-] detaches and returns you to the list. m attaches to the QEMU monitor the same way.

Keys

↑ ↓ / j k move between machines
/ filter the list by name
n e C d new, edit, clone, delete
s x p r start, stop, pause/resume, reset
c m attach serial console / QEMU monitor (Ctrl-] to detach)
l v view the QEMU log / the exact launch command
i a disk image tools / snapshots
I CD-ROM: eject or insert an ISO
P screenshot the guest display
? help

Forms save with F10 or Ctrl-S and cancel with Esc. On a path field — the ISO or disk image — Enter opens a file browser, filtered to the relevant file types; Tab or the arrow keys move on without opening it. You can also type a path directly.

Command line

A few operations are scriptable:

qemu-tui list             # machines and their state
qemu-tui start <name>
qemu-tui stop <name>      # ACPI shutdown request
qemu-tui kill <name>      # SIGKILL
qemu-tui status <name>    # exits 0 if running, 3 if not
qemu-tui paths            # where configs, disks and sockets live

How it works

Each machine is a plain key = value file you can read, diff and check into version control:

~/.config/qemu-tui/vms/<name>.conf     configuration
~/.local/share/qemu-tui/disks/         disk images
$XDG_RUNTIME_DIR/qemu-tui/<name>/      sockets, pidfile and launch log

VMs are started with -daemonize, so they keep running when you quit the interface — and are picked up again next time you start it. Each one exposes three unix sockets: QMP for programmatic control, the QEMU monitor, and a serial port. Live state (running/paused, uptime, memory) comes from QMP; i and a drive qemu-img and the monitor for disk and snapshot work.

Because QEMU serves a single QMP client at a time, the manager holds one connection per running VM and reuses it, rather than reconnecting on each poll.

Anything the interface does not model can go in the Extra args field, which is appended verbatim to the command line. Press v to see exactly what will be run before starting a machine.

CD-ROM

I opens the media menu: eject the current ISO, or insert a different one. On a running machine the change is applied live through QMP, so you can eject an installer and reboot straight into the installed system without stopping the VM. If the guest has the drive locked — usually because the disc is still mounted — you are offered a forced eject.

The configuration is updated either way, so the change survives a restart. When you eject while boot is set to cdrom, the boot order switches to disk, since booting from a drive you just emptied only stalls at the firmware.

A machine started with no ISO has no CD-ROM drive at all, and QEMU cannot add one to a running guest; the menu says so and the change takes effect on next start.

UEFI

Turning on UEFI attaches firmware the way modern OVMF expects: the read-only code image as pflash unit 0, and a private copy of the variable store as unit 1, kept in ~/.local/share/qemu-tui/nvram/<name>_VARS.fd. Boot entries the guest writes therefore persist, and machines never share NVRAM.

Firmware is located through QEMU's own descriptors in /usr/share/qemu/firmware/*.json, so whatever your distribution installs is found automatically — including non-x86 targets. Well-known OVMF/AAVMF paths are tried as a fallback. Note that today's OVMF.fd is usually a code-only image: it cannot be loaded with -bios, which is why it is attached as flash.

Snapshots

Snapshots are qcow2 internal snapshots. When a VM is running they go through the monitor (savevm/loadvm, capturing live RAM); when it is stopped they use qemu-img snapshot on the image.

Cloning

C offers a linked clone — an instant copy-on-write overlay on top of the original image — or a full copy. Either way the clone gets a fresh MAC address and VNC display so it cannot collide with the machine it came from.

Notes and limitations

  • Linux only: process and memory state are read from /proc.
  • bridge networking needs a configured qemu-bridge-helper; tap needs the interface to exist already. user mode works without any privileges.
  • A linked clone depends on its backing file — deleting the original breaks it.
  • Set ESCDELAY (milliseconds) if Esc feels slow or arrow keys misbehave over a high-latency SSH link. The default is 100.