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/.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- 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/.qcow2 Default location for newly created disk images. ~/.cache/qemu-tui/monitors/.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