emmett1/qemu-tui
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
qemu-tui/README
T
emmett1 39f7d98755 initial commit
2026-04-02 00:14:22 +08:00

356 lines
11 KiB
Plaintext
Raw Permalink Blame History

QEMU-TUI
========
A terminal UI for managing QEMU virtual machines.
Zero external dependencies -- uses only Python's built-in curses module.
REQUIREMENTS
------------
Python 3.7 or later
qemu-system-* binaries on your PATH
qemu-img (for disk management and snapshots)
/dev/kvm (optional, auto-detected for hardware acceleration)
OVMF firmware (optional, auto-detected for UEFI boot)
INSTALLATION
------------
No pip install needed. Just make the script executable:
chmod +x qemu-tui.py
./qemu-tui.py
Or copy it somewhere on your PATH:
cp qemu-tui.py ~/.local/bin/qemu-tui
chmod +x ~/.local/bin/qemu-tui
qemu-tui
LAYOUT
------
The screen is divided into two panes separated by a vertical line.
Left sidebar
Lists all VMs with a live status icon and state label.
Key hints are shown at the bottom of the sidebar.
Status icons:
> running
. stopped
~ paused
! error
Right panel
Shows details for the currently selected VM.
A header line shows the VM name, status, PID, and uptime.
Below it are six tabs selectable with the Tab key:
Info VM configuration and runtime info
Command The exact qemu-system-* command line
Log Live stdout/stderr from the QEMU process
Disk Disk image details and management hint
Snapshots List of internal qcow2 snapshots
Monitor QEMU monitor socket status and quick reference
Status bar
The bottom row shows the result of the last action in green
(success) or red (error).
KEYBINDINGS
-----------
Navigation
Up / Down Move between VMs in the sidebar
Tab Cycle through tabs
PgUp / PgDn Scroll log or console output
q Quit
VM lifecycle
n New VM
e Edit VM config (VM must be stopped)
Del Delete VM (VM must be stopped)
s Start VM
k Stop VM via SIGTERM (requests graceful OS shutdown)
F Force kill VM via SIGKILL (immediate termination)
g Graceful ACPI power-off via monitor socket
z Pause / resume toggle via monitor socket
Features
d Open disk management menu
p Open snapshot manager
f Open port forwarding editor
~ Open interactive QEMU monitor console
c Clone VM
i Import existing disk image as new VM
x Eject CD-ROM / ISO
TABS
----
Info
Displays all VM settings, current PID, uptime, UEFI firmware path
(or a warning if OVMF is not found), and port forwarding rules.
Command
Shows the full qemu-system-* command that will be used to start the
VM, wrapped across multiple lines for readability. Useful for
debugging or copying the command to run manually.
Log
Streams live stdout and stderr output from the QEMU process.
Scroll with PgUp and PgDn. Output is buffered up to 500 lines.
Disk
Shows the disk image path, format, virtual size, actual used space
with a percentage, snapshot count, and backing file if any.
If the disk is locked by a running VM, a friendly note is shown
instead of a raw error.
Press 'd' to open the disk management menu:
Create -- create a new qcow2 image (prompts for path and size)
Resize -- expand the disk to a new size (VM must be stopped)
Convert -- convert to qcow2, raw, vmdk, or vdi (VM must be stopped)
Delete -- permanently delete the disk file (VM must be stopped)
Snapshots
Lists all internal qcow2 snapshots with ID, name, date, and VM
clock time. If the disk is locked, a note is shown instead.
Press 'p' to open the snapshot manager:
c Create a snapshot (allowed while VM is running)
r Restore a snapshot (VM must be stopped)
x / Del Delete a snapshot (VM must be stopped)
R Refresh the list
Esc Close
Snapshot names cannot contain spaces.
Monitor
When the VM is running, shows the path of the QEMU monitor Unix
socket and a quick-reference of useful monitor commands.
Press '~' to open the interactive monitor console:
Left pane Quick-command list. Tab to focus, Up/Down to navigate,
Enter to run the selected command.
Right pane Scrollable output area. Cleared on each new command.
Scroll with PgUp / PgDn.
Bottom bar Free-form command input. Tab to focus, Enter to send.
Esc Close the console.
Useful monitor commands:
info status Current VM state
info network Network interfaces
info block Block devices and disk images
info cpus 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 (like pressing the reset button)
stop Pause execution
cont Resume execution
VM CONFIGURATION
----------------
Fields available when creating or editing a VM:
Name
Identifier for the VM. Also used as the default disk filename:
~/.cache/qemu-tui/<name>.qcow2
Memory (MiB)
RAM allocated to the VM. e.g. 1024, 2048, 4096.
CPUs
Number of virtual CPU cores.
Disk image
Path to the qcow2 (or other format) disk image.
Press Enter or B on this field to open the file browser.
Default path is set automatically from the VM name.
If the file does not exist when you save, you are offered
the option to create it.
CD-ROM / ISO
Path to an ISO or image file to attach as a CD-ROM drive.
Press Enter or B to browse. Press 'x' from the main screen
to eject.
Architecture
One of: x86_64, aarch64, arm, riscv64, mips.
The matching qemu-system-<arch> binary is used.
Network
user -- NAT networking via SLIRP. Supports port forwarding.
none -- No network interface.
Display
none -- Headless. No graphical output. Use SSH to access.
sdl -- Opens an SDL window on the local display.
vnc -- Listens on VNC port 5900.
UEFI / OVMF
Enables UEFI firmware. The manager searches common paths for
an OVMF firmware file automatically. The detected path is shown
inline when the field is selected. If no firmware is found,
an error is shown in the Info tab.
Extra args
Additional raw arguments appended verbatim to the qemu-system-*
command line. Parsed with shlex so quoting is respected.
PORT FORWARDING
---------------
Only available when network is set to 'user'.
Press 'f' to open the editor. Press 'a' to add a rule.
A preset picker appears first:
SSH tcp host 2222 -> guest 22
HTTP tcp host 8080 -> guest 80
HTTPS tcp host 8443 -> guest 443
RDP tcp host 3389 -> guest 3389
VNC tcp host 5900 -> guest 5900
Custom enter all fields manually
After choosing a preset you can override all values:
Protocol tcp or udp
Host port port on the physical machine
Guest port port inside the VM
Host bind addr leave blank to listen on all interfaces
Description optional label shown in the rule list
Rules are saved with the VM config and injected as hostfwd= entries
in the -netdev user argument. Changes take effect on the next start.
d / Del Delete the selected rule
Esc Save and close
CLONE VM
--------
Press 'c' (VM must be stopped). Enter a new name, then choose a
disk copy mode:
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.
Full copy
Runs qemu-img convert to produce a completely independent copy.
Takes time proportional to the virtual disk size and uses the
same amount of storage. Safe to use without the original.
No copy
Clones only the config. Both VMs point at the same disk file.
Running both simultaneously will corrupt the disk.
Port forwarding rules are not copied to avoid host port conflicts.
After cloning the new VM is selected automatically.
IMPORT VM
---------
Press 'i' to import an existing disk image as a new VM.
A file browser opens, filtered to common disk image extensions:
.qcow2 .img .raw .vmdk .vdi .iso
After selecting a file:
1. qemu-img info is run to detect the format and virtual size.
2. A brief summary is shown.
3. You are prompted for a VM name (defaults to the filename stem).
4. A VM config is created pointing at the selected file.
If the format is not qcow2 the correct -drive format= flag
is set via extra args.
After importing the new VM is selected automatically.
UEFI / OVMF
-----------
Enable the 'UEFI / OVMF' toggle in the VM form.
The manager searches these paths in order (x86_64):
/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
For aarch64:
/usr/share/AAVMF/AAVMF_CODE.fd
/usr/share/qemu-efi-aarch64/QEMU_EFI.fd
Install on common distributions:
Arch Linux / Void Linux
sudo pacman -S edk2-ovmf
sudo xbps-install edk2-ovmf
Debian / Ubuntu
sudo apt install ovmf
Fedora
sudo dnf install edk2-ovmf
KVM ACCELERATION
----------------
Detected automatically. If /dev/kvm exists, the flags
-enable-kvm -cpu host
are added to the command, giving near-native CPU performance.
To enable KVM on Linux:
sudo usermod -aG kvm $USER
(log out and back in for the group change to take effect)
If KVM is not available QEMU falls back to software emulation,
which is significantly slower.
FILE LOCATIONS
--------------
~/.config/qemu-tui/vms.json
VM configurations. Edited by the manager; do not modify
while the manager is running.
~/.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 VMs.
~/.cache/qemu-tui/<name>.qcow2
Default location for newly created disk images.
~/.cache/qemu-tui/monitors/<name>.sock
QEMU monitor Unix domain socket for each running VM.
SESSION PERSISTENCE
-------------------
VMs started by qemu-tui are ordinary background processes. Closing
the manager does not stop them.
When qemu-tui starts it reads runtime.json and for each entry sends
signal 0 (kill -0) to the saved PID to check whether the process is
still alive. If it is, the VM is shown as 'running' with its original
start time and monitor socket path restored.
All actions work on re-attached VMs:
k Stop (SIGTERM)
F Force kill (SIGKILL)
g ACPI power-off via monitor
z Pause / resume via monitor
~ Open monitor console
Reference in New Issue View Git Blame Copy Permalink