qemu-tui.1 (12245B)
1 .TH QEMU\-TUI 1 "March 2026" "qemu-tui" "User Commands" 2 .SH NAME 3 qemu\-tui \- terminal UI for managing QEMU virtual machines 4 .SH SYNOPSIS 5 .B qemu\-tui 6 .SH DESCRIPTION 7 .B qemu\-tui 8 is an interactive terminal user interface for creating, configuring, 9 and controlling QEMU virtual machines. 10 It requires no external Python packages \(em only the standard library 11 .B curses 12 module. 13 .PP 14 The interface is divided into a left sidebar listing all VMs with live 15 status and a right panel showing details for the selected VM across six 16 tabs: Info, Command, Log, Disk, Snapshots, and Monitor. 17 A status bar at the bottom reports the result of each action. 18 .SH REQUIREMENTS 19 .TP 20 .B Python 3.7+ 21 .TP 22 .BR qemu\-system\-* (1) 23 on PATH 24 .TP 25 .BR qemu\-img (1) 26 for disk management and snapshots 27 .TP 28 .I /dev/kvm 29 for hardware acceleration (optional, auto-detected) 30 .TP 31 .B OVMF firmware 32 for UEFI boot (optional, auto-detected) 33 .SH LAYOUT 34 The screen has three areas. 35 .SS Left sidebar 36 Lists all configured VMs. 37 Each entry shows the VM name and current status icon: 38 .TP 39 .B > 40 running 41 .TP 42 .B \&. 43 stopped 44 .TP 45 .B ~ 46 paused 47 .TP 48 .B ! 49 error 50 .PP 51 Key hints are printed at the bottom of the sidebar. 52 .SS Right panel 53 Shows the selected VM across six tabs, selectable with 54 .BR Tab : 55 .TP 56 .B Info 57 All VM configuration fields, current PID, uptime, UEFI firmware path, 58 and port forwarding rules. 59 .TP 60 .B Command 61 The exact 62 .B qemu\-system\-* 63 command line that will be used to start the VM. 64 .TP 65 .B Log 66 Live stdout and stderr from the QEMU process, buffered to 500 lines. 67 .TP 68 .B Disk 69 Disk image format, virtual size, actual used space, snapshot count, 70 and backing file. 71 .TP 72 .B Snapshots 73 List of internal qcow2 snapshots with ID, name, date, and VM clock time. 74 .TP 75 .B Monitor 76 QEMU monitor socket status and quick-command reference. 77 .SS Status bar 78 The bottom row shows the result of the last action in green (success) 79 or red (error). 80 .SH KEYS 81 .SS Navigation 82 .TP 83 .B Up / Down 84 Move between VMs in the sidebar. 85 .TP 86 .B Tab 87 Cycle through the six tabs. 88 .TP 89 .B PgUp / PgDn 90 Scroll the Log or monitor console output. 91 .TP 92 .B q 93 Quit. 94 .SS VM Lifecycle 95 .TP 96 .B n 97 Create a new VM. 98 .TP 99 .B e 100 Edit the selected VM's configuration. 101 The VM must be stopped. 102 .TP 103 .B Del 104 Delete the selected VM. 105 The VM must be stopped. 106 The disk image is not deleted automatically. 107 .TP 108 .B s 109 Start the selected VM. 110 .TP 111 .B k 112 Stop the VM by sending SIGTERM. 113 Requests a graceful shutdown from the guest OS. 114 .TP 115 .B F 116 Force kill the VM with SIGKILL. 117 Takes effect immediately. 118 .TP 119 .B g 120 Send an ACPI power button signal via the QEMU monitor socket. 121 The guest OS receives a polite shutdown request. 122 The VM must be running. 123 .TP 124 .B z 125 Toggle pause and resume via the QEMU monitor socket. 126 .SS Feature Keys 127 .TP 128 .B d 129 Open the disk management menu. 130 .TP 131 .B p 132 Open the snapshot manager. 133 .TP 134 .B f 135 Open the port forwarding editor. 136 Only available when network is set to 137 .BR user . 138 .TP 139 .B ~ 140 Open the interactive QEMU monitor console. 141 .TP 142 .B c 143 Clone the selected VM. 144 The VM must be stopped. 145 .TP 146 .B i 147 Import an existing disk image as a new VM. 148 .TP 149 .B x 150 Eject the attached CD-ROM or ISO image. 151 .SH VM CONFIGURATION 152 Fields available in the new/edit form. 153 Navigate rows with 154 .B Tab 155 or arrow keys. 156 Use 157 .B Left / Right 158 to cycle option fields. 159 Press 160 .B Enter 161 or 162 .B B 163 on path fields to open the file browser. 164 Press 165 .B S 166 to save, 167 .B Esc 168 to cancel. 169 .TP 170 .B Name 171 Identifier for the VM. 172 Also used as the default disk filename 173 .RI ( ~/.cache/qemu\-tui/<n>.qcow2 ). 174 .TP 175 .B Memory (MiB) 176 RAM allocated to the VM in mebibytes. 177 .TP 178 .B CPUs 179 Number of virtual CPU cores. 180 .TP 181 .B Disk image 182 Path to the disk image file. 183 If the file does not exist when the form is saved, an option to create 184 a new qcow2 image is offered. 185 .TP 186 .B CD-ROM / ISO 187 Path to an ISO to attach as a CD-ROM. 188 Press 189 .B x 190 from the main screen to eject. 191 .TP 192 .B Architecture 193 One of: 194 .BR x86_64 , 195 .BR aarch64 , 196 .BR arm , 197 .BR riscv64 , 198 .BR mips . 199 The matching 200 .B qemu\-system\-<arch> 201 binary is invoked. 202 .TP 203 .B Network 204 .B user 205 \(em NAT via SLIRP with optional port forwarding rules. 206 .br 207 .B none 208 \(em no network interface. 209 .TP 210 .B Display 211 .B none 212 \(em headless, no graphical output. 213 .br 214 .B sdl 215 \(em opens an SDL window on the local display. 216 .br 217 .B vnc 218 \(em listens on VNC port 5900. 219 .TP 220 .B UEFI / OVMF 221 Enables UEFI firmware. 222 The manager auto-detects installed OVMF firmware files. 223 The detected path is shown inline when this field is selected. 224 .TP 225 .B Extra args 226 Additional arguments appended verbatim to the 227 .B qemu\-system\-* 228 invocation, parsed with 229 .BR shlex . 230 .SH DISK MANAGEMENT 231 Opened by pressing 232 .B d 233 when a VM is selected. 234 Navigate actions with 235 .B Up 236 / 237 .B Down 238 and execute with 239 .BR Enter . 240 Press 241 .B R 242 to refresh disk information. 243 Press 244 .B Esc 245 to close. 246 .TP 247 .B Show disk info 248 Runs 249 .B qemu\-img info 250 on the current disk file and refreshes the displayed statistics. 251 Available while the VM is running. 252 .TP 253 .B Create new disk 254 Prompts for a file path and size in gibibytes, then runs: 255 .PP 256 .nf 257 qemu\-img create \-f qcow2 <path> <size>G 258 .fi 259 .PP 260 If the VM has no disk configured the new file is set as its disk 261 automatically. 262 Available while the VM is running. 263 .TP 264 .B Resize disk 265 Prompts for a new size in gibibytes and runs: 266 .PP 267 .nf 268 qemu\-img resize <path> <size>G 269 .fi 270 .PP 271 Disks can only be grown, not shrunk. 272 The filesystem inside the guest must be expanded separately. 273 .B The VM must be stopped. 274 .TP 275 .B Convert to another format 276 Prompts for a destination path and target format, then runs: 277 .PP 278 .nf 279 qemu\-img convert \-p \-O <fmt> <src> <dst> 280 .fi 281 .PP 282 Supported formats: 283 .BR qcow2 , 284 .BR raw , 285 .BR vmdk , 286 .BR vdi . 287 .B The VM must be stopped. 288 .TP 289 .B Delete disk file 290 Prompts for confirmation then permanently removes the disk image file. 291 This action cannot be undone. 292 .B The VM must be stopped. 293 .SH SNAPSHOTS 294 Opened by pressing 295 .B p 296 when a VM is selected. 297 The manager displays a table with columns ID, Tag/Name, Date, and 298 VM Clock. 299 Navigate with 300 .B Up 301 / 302 .BR Down . 303 .TP 304 .B c 305 Create a new snapshot. 306 Prompts for a name (no spaces allowed). 307 The VM may be running. 308 .TP 309 .B r 310 Restore the selected snapshot. 311 Reverts the disk to the captured state; changes since the snapshot are 312 discarded. 313 .B The VM must be stopped. 314 .TP 315 .B x / Del 316 Delete the selected snapshot. 317 .B The VM must be stopped. 318 .TP 319 .B R 320 Refresh the snapshot list. 321 .TP 322 .B Esc 323 Close the manager. 324 .PP 325 Snapshots use these 326 .BR qemu\-img (1) 327 subcommands internally: 328 .PP 329 .nf 330 qemu\-img snapshot \-l <disk> (list) 331 qemu\-img snapshot \-c <tag> <disk> (create) 332 qemu\-img snapshot \-a <tag> <disk> (restore) 333 qemu\-img snapshot \-d <tag> <disk> (delete) 334 .fi 335 .PP 336 Snapshots require qcow2 format. 337 Restoring a snapshot does not restore guest RAM state. 338 .SH PORT FORWARDING 339 Opened by pressing 340 .B f 341 when a VM is selected. 342 Only available when network is set to 343 .BR user . 344 .PP 345 The editor shows a table with columns Proto, Host addr, Host port, 346 Guest port, and Desc. 347 Navigate with 348 .B Up 349 / 350 .BR Down . 351 .TP 352 .B a 353 Add a new rule. 354 A preset picker is shown first: 355 .TS 356 l l l l. 357 Preset Protocol Host port Guest port 358 _ 359 SSH tcp 2222 22 360 HTTP tcp 8080 80 361 HTTPS tcp 8443 443 362 RDP tcp 3389 3389 363 VNC tcp 5900 5900 364 Custom (prompt) (prompt) (prompt) 365 .TE 366 .PP 367 After choosing a preset you are prompted to confirm or override the 368 protocol, host port, guest port, host bind address (blank = all 369 interfaces), and an optional description. 370 .TP 371 .B d / Del 372 Delete the selected rule (with confirmation). 373 .TP 374 .B Esc 375 Save all rules and close the editor. 376 .PP 377 Rules are stored in the VM configuration and injected as 378 .B hostfwd= 379 entries in the 380 .B \-netdev user 381 argument on the next VM start: 382 .PP 383 .nf 384 \-netdev user,id=net0,hostfwd=tcp::2222\-:22 385 .fi 386 .PP 387 To SSH into a headless VM after adding an SSH rule: 388 .PP 389 .nf 390 ssh \-p 2222 user@localhost 391 .fi 392 .SH MONITOR CONSOLE 393 Press 394 .B ~ 395 to open the interactive QEMU monitor console for the selected VM. 396 The console is divided into three areas: 397 .TP 398 .B Left pane 399 A quick-command list. 400 Press 401 .B Tab 402 to focus, 403 .B Up 404 / 405 .B Down 406 to navigate, and 407 .B Enter 408 to run the selected command. 409 .TP 410 .B Right pane 411 Scrollable output area, cleared on each new command. 412 Scroll with 413 .B PgUp 414 / 415 .BR PgDn . 416 .TP 417 .B Input line 418 Free-form command entry. 419 Press 420 .B Tab 421 to focus, type a command, and press 422 .B Enter 423 to send. 424 .PP 425 Press 426 .B Esc 427 to close. 428 .PP 429 Useful monitor commands: 430 .TS 431 l l. 432 Command Description 433 _ 434 info status Current VM execution state 435 info network Network interface details 436 info block Block devices and disk images 437 info cpus Virtual CPU information 438 info mem Memory map 439 info pci PCI device list 440 info snapshots Snapshot list (live) 441 system_powerdown Send ACPI power button signal 442 system_reset Hard reset the VM 443 stop Pause VM execution 444 cont Resume paused VM 445 .TE 446 .PP 447 The 448 .B g 449 and 450 .B z 451 keys on the main screen are shortcuts for 452 .B system_powerdown 453 and 454 .BR stop / cont 455 respectively, without opening the console. 456 .SH CLONE VM 457 Press 458 .B c 459 (VM must be stopped). 460 Enter a new name, then select a disk copy mode: 461 .TP 462 .B Linked clone 463 Creates a new qcow2 image with the original disk as a backing file. 464 Very small and instant. 465 Writes from the clone go to the new file; the original is not modified. 466 Requires the original disk to remain accessible at its original path. 467 .TP 468 .B Full copy 469 Runs 470 .B qemu\-img convert 471 to produce a completely independent copy. 472 Takes time proportional to the virtual disk size. 473 Safe to move or delete the original afterwards. 474 .TP 475 .B No copy 476 Clones only the configuration. 477 Both VMs share the same disk file. 478 Running both simultaneously will corrupt the disk. 479 .PP 480 Port forwarding rules are not copied to avoid host port conflicts. 481 After cloning the new VM is automatically selected. 482 .SH IMPORT VM 483 Press 484 .B i 485 to import an existing disk image as a new VM. 486 A file browser opens filtered to: 487 .BR .qcow2 , 488 .BR .img , 489 .BR .raw , 490 .BR .vmdk , 491 .BR .vdi , 492 .BR .iso . 493 .PP 494 After selecting a file: 495 .IP 1. 4 496 .B qemu\-img info 497 is run to detect the format and virtual size. 498 .IP 2. 4 499 A brief summary is shown. 500 .IP 3. 4 501 You are prompted for a VM name (defaults to the filename stem). 502 .IP 4. 4 503 A VM configuration is created pointing at the disk. 504 If the format is not qcow2 the correct 505 .B \-drive format= 506 flag is set via extra args. 507 .PP 508 After importing the new VM is automatically selected. 509 .SH UEFI / OVMF 510 Enable the 511 .B UEFI / OVMF 512 toggle in the VM form. 513 The manager searches these paths in order for x86_64: 514 .PP 515 .nf 516 /usr/share/ovmf/OVMF.fd 517 /usr/share/ovmf/x64/OVMF.fd 518 /usr/share/OVMF/OVMF_CODE.fd 519 /usr/share/edk2/ovmf/OVMF_CODE.fd 520 /usr/share/edk2-ovmf/OVMF_CODE.fd 521 /usr/lib/ovmf/OVMF.fd 522 /usr/share/qemu/ovmf-x86_64.bin 523 .fi 524 .PP 525 For aarch64: 526 .PP 527 .nf 528 /usr/share/AAVMF/AAVMF_CODE.fd 529 /usr/share/qemu-efi-aarch64/QEMU_EFI.fd 530 .fi 531 .PP 532 Install OVMF on common distributions: 533 .PP 534 .nf 535 Arch Linux: sudo pacman -S edk2-ovmf 536 Void Linux: sudo xbps-install edk2-ovmf 537 Debian/Ubuntu: sudo apt install ovmf 538 Fedora: sudo dnf install edk2-ovmf 539 .fi 540 .SH KVM ACCELERATION 541 If 542 .I /dev/kvm 543 exists the flags 544 .B \-enable\-kvm \-cpu host 545 are added automatically for near-native CPU performance. 546 .PP 547 To enable KVM: 548 .PP 549 .nf 550 sudo usermod \-aG kvm $USER 551 .fi 552 .PP 553 Log out and back in for the group change to take effect. 554 .SH SESSION PERSISTENCE 555 VMs started by 556 .B qemu\-tui 557 are ordinary background processes. 558 Closing the manager does not stop them. 559 .PP 560 On startup the manager reads 561 .I ~/.cache/qemu\-tui/runtime.json 562 and sends signal 0 to each saved PID to check whether the process is 563 still alive. 564 If it is, the VM is shown as 565 .B running 566 with its original start time and monitor socket path restored. 567 All actions (stop, force kill, ACPI shutdown, pause, resume, and the 568 monitor console) work on re-attached VMs. 569 .SH FILES 570 .TP 571 .I ~/.config/qemu\-tui/vms.json 572 VM configurations. 573 Do not edit while the manager is running. 574 .TP 575 .I ~/.cache/qemu\-tui/runtime.json 576 Runtime state: PID, start time, status, and monitor socket path for 577 each running or paused VM. 578 Written on every start and stop. 579 Read on startup to re-attach to surviving processes. 580 .TP 581 .I ~/.cache/qemu\-tui/<n>.qcow2 582 Default location for newly created disk images. 583 .TP 584 .I ~/.cache/qemu\-tui/monitors/<n>.sock 585 QEMU monitor Unix domain socket for each running VM. 586 .SH SEE ALSO 587 .BR qemu\-system\-x86_64 (1), 588 .BR qemu\-img (1), 589 .BR qemu\-system\-aarch64 (1) 590 .SH AUTHOR 591 Written by Emmett.