path: root/qemu-tui.1

.TH QEMU\-TUI 1 "March 2026" "qemu-tui" "User Commands"
.SH NAME
qemu\-tui \- terminal UI for managing QEMU virtual machines
.SH SYNOPSIS
.B qemu\-tui
.SH DESCRIPTION
.B qemu\-tui
is an interactive terminal user interface for creating, configuring,
and controlling QEMU virtual machines.
It requires no external Python packages \(em only the standard library
.B curses
module.
.PP
The interface is divided into a left sidebar listing all VMs with live
status and a right panel showing details for the selected VM across six
tabs: Info, Command, Log, Disk, Snapshots, and Monitor.
A status bar at the bottom reports the result of each action.
.SH REQUIREMENTS
.TP
.B Python 3.7+
.TP
.BR qemu\-system\-* (1)
on PATH
.TP
.BR qemu\-img (1)
for disk management and snapshots
.TP
.I /dev/kvm
for hardware acceleration (optional, auto-detected)
.TP
.B OVMF firmware
for UEFI boot (optional, auto-detected)
.SH LAYOUT
The screen has three areas.
.SS Left sidebar
Lists all configured VMs.
Each entry shows the VM name and current status icon:
.TP
.B >
running
.TP
.B \&.
stopped
.TP
.B ~
paused
.TP
.B !
error
.PP
Key hints are printed at the bottom of the sidebar.
.SS Right panel
Shows the selected VM across six tabs, selectable with
.BR Tab :
.TP
.B Info
All VM configuration fields, current PID, uptime, UEFI firmware path,
and port forwarding rules.
.TP
.B Command
The exact
.B qemu\-system\-*
command line that will be used to start the VM.
.TP
.B Log
Live stdout and stderr from the QEMU process, buffered to 500 lines.
.TP
.B Disk
Disk image format, virtual size, actual used space, snapshot count,
and backing file.
.TP
.B Snapshots
List of internal qcow2 snapshots with ID, name, date, and VM clock time.
.TP
.B Monitor
QEMU monitor socket status and quick-command reference.
.SS Status bar
The bottom row shows the result of the last action in green (success)
or red (error).
.SH KEYS
.SS Navigation
.TP
.B Up / Down
Move between VMs in the sidebar.
.TP
.B Tab
Cycle through the six tabs.
.TP
.B PgUp / PgDn
Scroll the Log or monitor console output.
.TP
.B q
Quit.
.SS VM Lifecycle
.TP
.B n
Create a new VM.
.TP
.B e
Edit the selected VM's configuration.
The VM must be stopped.
.TP
.B Del
Delete the selected VM.
The VM must be stopped.
The disk image is not deleted automatically.
.TP
.B s
Start the selected VM.
.TP
.B k
Stop the VM by sending SIGTERM.
Requests a graceful shutdown from the guest OS.
.TP
.B F
Force kill the VM with SIGKILL.
Takes effect immediately.
.TP
.B g
Send an ACPI power button signal via the QEMU monitor socket.
The guest OS receives a polite shutdown request.
The VM must be running.
.TP
.B z
Toggle pause and resume via the QEMU monitor socket.
.SS Feature Keys
.TP
.B d
Open the disk management menu.
.TP
.B p
Open the snapshot manager.
.TP
.B f
Open the port forwarding editor.
Only available when network is set to
.BR user .
.TP
.B ~
Open the interactive QEMU monitor console.
.TP
.B c
Clone the selected VM.
The VM must be stopped.
.TP
.B i
Import an existing disk image as a new VM.
.TP
.B x
Eject the attached CD-ROM or ISO image.
.SH VM CONFIGURATION
Fields available in the new/edit form.
Navigate rows with
.B Tab
or arrow keys.
Use
.B Left / Right
to cycle option fields.
Press
.B Enter
or
.B B
on path fields to open the file browser.
Press
.B S
to save,
.B Esc
to cancel.
.TP
.B Name
Identifier for the VM.
Also used as the default disk filename
.RI ( ~/.cache/qemu\-tui/<n>.qcow2 ).
.TP
.B Memory (MiB)
RAM allocated to the VM in mebibytes.
.TP
.B CPUs
Number of virtual CPU cores.
.TP
.B Disk image
Path to the disk image file.
If the file does not exist when the form is saved, an option to create
a new qcow2 image is offered.
.TP
.B CD-ROM / ISO
Path to an ISO to attach as a CD-ROM.
Press
.B x
from the main screen to eject.
.TP
.B Architecture
One of:
.BR x86_64 ,
.BR aarch64 ,
.BR arm ,
.BR riscv64 ,
.BR mips .
The matching
.B qemu\-system\-<arch>
binary is invoked.
.TP
.B Network
.B user
\(em NAT via SLIRP with optional port forwarding rules.
.br
.B none
\(em no network interface.
.TP
.B Display
.B none
\(em headless, no graphical output.
.br
.B sdl
\(em opens an SDL window on the local display.
.br
.B vnc
\(em listens on VNC port 5900.
.TP
.B UEFI / OVMF
Enables UEFI firmware.
The manager auto-detects installed OVMF firmware files.
The detected path is shown inline when this field is selected.
.TP
.B Extra args
Additional arguments appended verbatim to the
.B qemu\-system\-*
invocation, parsed with
.BR shlex .
.SH DISK MANAGEMENT
Opened by pressing
.B d
when a VM is selected.
Navigate actions with
.B Up
/
.B Down
and execute with
.BR Enter .
Press
.B R
to refresh disk information.
Press
.B Esc
to close.
.TP
.B Show disk info
Runs
.B qemu\-img info
on the current disk file and refreshes the displayed statistics.
Available while the VM is running.
.TP
.B Create new disk
Prompts for a file path and size in gibibytes, then runs:
.PP
.nf
    qemu\-img create \-f qcow2 <path> <size>G
.fi
.PP
If the VM has no disk configured the new file is set as its disk
automatically.
Available while the VM is running.
.TP
.B Resize disk
Prompts for a new size in gibibytes and runs:
.PP
.nf
    qemu\-img resize <path> <size>G
.fi
.PP
Disks can only be grown, not shrunk.
The filesystem inside the guest must be expanded separately.
.B The VM must be stopped.
.TP
.B Convert to another format
Prompts for a destination path and target format, then runs:
.PP
.nf
    qemu\-img convert \-p \-O <fmt> <src> <dst>
.fi
.PP
Supported formats:
.BR qcow2 ,
.BR raw ,
.BR vmdk ,
.BR vdi .
.B The VM must be stopped.
.TP
.B Delete disk file
Prompts for confirmation then permanently removes the disk image file.
This action cannot be undone.
.B The VM must be stopped.
.SH SNAPSHOTS
Opened by pressing
.B p
when a VM is selected.
The manager displays a table with columns ID, Tag/Name, Date, and
VM Clock.
Navigate with
.B Up
/
.BR Down .
.TP
.B c
Create a new snapshot.
Prompts for a name (no spaces allowed).
The VM may be running.
.TP
.B r
Restore the selected snapshot.
Reverts the disk to the captured state; changes since the snapshot are
discarded.
.B The VM must be stopped.
.TP
.B x / Del
Delete the selected snapshot.
.B The VM must be stopped.
.TP
.B R
Refresh the snapshot list.
.TP
.B Esc
Close the manager.
.PP
Snapshots use these
.BR qemu\-img (1)
subcommands internally:
.PP
.nf
    qemu\-img snapshot \-l <disk>        (list)
    qemu\-img snapshot \-c <tag> <disk>  (create)
    qemu\-img snapshot \-a <tag> <disk>  (restore)
    qemu\-img snapshot \-d <tag> <disk>  (delete)
.fi
.PP
Snapshots require qcow2 format.
Restoring a snapshot does not restore guest RAM state.
.SH PORT FORWARDING
Opened by pressing
.B f
when a VM is selected.
Only available when network is set to
.BR user .
.PP
The editor shows a table with columns Proto, Host addr, Host port,
Guest port, and Desc.
Navigate with
.B Up
/
.BR Down .
.TP
.B a
Add a new rule.
A preset picker is shown first:
.TS
l l l l.
Preset	Protocol	Host port	Guest port
_
SSH	tcp	2222	22
HTTP	tcp	8080	80
HTTPS	tcp	8443	443
RDP	tcp	3389	3389
VNC	tcp	5900	5900
Custom	(prompt)	(prompt)	(prompt)
.TE
.PP
After choosing a preset you are prompted to confirm or override the
protocol, host port, guest port, host bind address (blank = all
interfaces), and an optional description.
.TP
.B d / Del
Delete the selected rule (with confirmation).
.TP
.B Esc
Save all rules and close the editor.
.PP
Rules are stored in the VM configuration and injected as
.B hostfwd=
entries in the
.B \-netdev user
argument on the next VM start:
.PP
.nf
    \-netdev user,id=net0,hostfwd=tcp::2222\-:22
.fi
.PP
To SSH into a headless VM after adding an SSH rule:
.PP
.nf
    ssh \-p 2222 user@localhost
.fi
.SH MONITOR CONSOLE
Press
.B ~
to open the interactive QEMU monitor console for the selected VM.
The console is divided into three areas:
.TP
.B Left pane
A quick-command list.
Press
.B Tab
to focus,
.B Up
/
.B Down
to navigate, and
.B Enter
to run the selected command.
.TP
.B Right pane
Scrollable output area, cleared on each new command.
Scroll with
.B PgUp
/
.BR PgDn .
.TP
.B Input line
Free-form command entry.
Press
.B Tab
to focus, type a command, and press
.B Enter
to send.
.PP
Press
.B Esc
to close.
.PP
Useful monitor commands:
.TS
l l.
Command	Description
_
info status	Current VM execution state
info network	Network interface details
info block	Block devices and disk images
info cpus	Virtual CPU information
info mem	Memory map
info pci	PCI device list
info snapshots	Snapshot list (live)
system_powerdown	Send ACPI power button signal
system_reset	Hard reset the VM
stop	Pause VM execution
cont	Resume paused VM
.TE
.PP
The
.B g
and
.B z
keys on the main screen are shortcuts for
.B system_powerdown
and
.BR stop / cont
respectively, without opening the console.
.SH CLONE VM
Press
.B c
(VM must be stopped).
Enter a new name, then select a disk copy mode:
.TP
.B Linked clone
Creates a new qcow2 image with the original disk as a backing file.
Very small and instant.
Writes from the clone go to the new file; the original is not modified.
Requires the original disk to remain accessible at its original path.
.TP
.B Full copy
Runs
.B qemu\-img convert
to produce a completely independent copy.
Takes time proportional to the virtual disk size.
Safe to move or delete the original afterwards.
.TP
.B No copy
Clones only the configuration.
Both VMs share the same disk file.
Running both simultaneously will corrupt the disk.
.PP
Port forwarding rules are not copied to avoid host port conflicts.
After cloning the new VM is automatically selected.
.SH IMPORT VM
Press
.B i
to import an existing disk image as a new VM.
A file browser opens filtered to:
.BR .qcow2 ,
.BR .img ,
.BR .raw ,
.BR .vmdk ,
.BR .vdi ,
.BR .iso .
.PP
After selecting a file:
.IP 1. 4
.B qemu\-img info
is run to detect the format and virtual size.
.IP 2. 4
A brief summary is shown.
.IP 3. 4
You are prompted for a VM name (defaults to the filename stem).
.IP 4. 4
A VM configuration is created pointing at the disk.
If the format is not qcow2 the correct
.B \-drive format=
flag is set via extra args.
.PP
After importing the new VM is automatically selected.
.SH UEFI / OVMF
Enable the
.B UEFI / OVMF
toggle in the VM form.
The manager searches these paths in order for x86_64:
.PP
.nf
    /usr/share/ovmf/OVMF.fd
    /usr/share/ovmf/x64/OVMF.fd
    /usr/share/OVMF/OVMF_CODE.fd
    /usr/share/edk2/ovmf/OVMF_CODE.fd
    /usr/share/edk2-ovmf/OVMF_CODE.fd
    /usr/lib/ovmf/OVMF.fd
    /usr/share/qemu/ovmf-x86_64.bin
.fi
.PP
For aarch64:
.PP
.nf
    /usr/share/AAVMF/AAVMF_CODE.fd
    /usr/share/qemu-efi-aarch64/QEMU_EFI.fd
.fi
.PP
Install OVMF on common distributions:
.PP
.nf
    Arch Linux:    sudo pacman -S edk2-ovmf
    Void Linux:    sudo xbps-install edk2-ovmf
    Debian/Ubuntu: sudo apt install ovmf
    Fedora:        sudo dnf install edk2-ovmf
.fi
.SH KVM ACCELERATION
If
.I /dev/kvm
exists the flags
.B \-enable\-kvm \-cpu host
are added automatically for near-native CPU performance.
.PP
To enable KVM:
.PP
.nf
    sudo usermod \-aG kvm $USER
.fi
.PP
Log out and back in for the group change to take effect.
.SH SESSION PERSISTENCE
VMs started by
.B qemu\-tui
are ordinary background processes.
Closing the manager does not stop them.
.PP
On startup the manager reads
.I ~/.cache/qemu\-tui/runtime.json
and sends signal 0 to each saved PID to check whether the process is
still alive.
If it is, the VM is shown as
.B running
with its original start time and monitor socket path restored.
All actions (stop, force kill, ACPI shutdown, pause, resume, and the
monitor console) work on re-attached VMs.
.SH FILES
.TP
.I ~/.config/qemu\-tui/vms.json
VM configurations.
Do not edit while the manager is running.
.TP
.I ~/.cache/qemu\-tui/runtime.json
Runtime state: PID, start time, status, and monitor socket path for
each running or paused VM.
Written on every start and stop.
Read on startup to re-attach to surviving processes.
.TP
.I ~/.cache/qemu\-tui/<n>.qcow2
Default location for newly created disk images.
.TP
.I ~/.cache/qemu\-tui/monitors/<n>.sock
QEMU monitor Unix domain socket for each running VM.
.SH SEE ALSO
.BR qemu\-system\-x86_64 (1),
.BR qemu\-img (1),
.BR qemu\-system\-aarch64 (1)
.SH AUTHOR
Written by Emmett.