- C++ 98.6%
- CMake 0.7%
- Makefile 0.7%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| src | ||
| tests | ||
| CMakeLists.txt | ||
| Makefile | ||
| README.md | ||
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. bridgenetworking needs a configuredqemu-bridge-helper;tapneeds the interface to exist already.usermode works without any privileges.- A linked clone depends on its backing file — deleting the original breaks it.
- Set
ESCDELAY(milliseconds) ifEscfeels slow or arrow keys misbehave over a high-latency SSH link. The default is 100.