Using quickemu (VM Launcher)
Relevant source files
The following files were used as context for generating this wiki page:
quickemu is a specialized Bash wrapper for QEMU designed to simplify the creation and execution of optimized virtual machines. It automates the complex configuration process by enumerating host hardware and applying settings best suited for the specific guest operating system. The primary goal is to provide a "just works" experience for running Windows, macOS, and Linux VMs without requiring deep technical knowledge of QEMU's exhaustive command-line options.
The launcher works in tandem with quickget, which handles the initial OS image acquisition and configuration file generation. Together, these tools allow for portable VM management where configurations can be stored in any directory—including external storage—without requiring elevated (root) permissions.
Sources: README.md:32-41, AGENTS.md:3-5
Core Architecture and Workflow
The Quickemu ecosystem is structured around modular Bash scripts that handle different stages of the VM lifecycle. quickemu specifically functions as the execution engine that interprets configuration files.
The Virtualization Pipeline
The following diagram illustrates the sequence from OS selection to a running virtual machine.
This flow ensures that the VM is not only created easily but is also tuned for the specific hardware it is running on.
Sources: README.md:88-99, AGENTS.md:3-8
Key Components
The project maintains several utilities to support the launcher's environment:
| Tool | Purpose |
|---|---|
quickemu | The main VM launcher script written in Bash. |
quickget | Downloads upstream OS images and generates the .conf files. |
quickreport | A diagnostics tool for system information and troubleshooting. |
chunkcheck | A utility for verifying the integrity of downloaded files. |
Sources: AGENTS.md:10-17
VM Configuration and Execution
To launch a virtual machine, quickemu requires a configuration file (typically ending in .conf). This file contains the metadata and hardware requirements defined during the quickget process.
Launch Command
The basic syntax for starting a VM is:
quickemu --vm <name>.conf
Sources: README.md:99, AGENTS.md:36
Hardware Optimization and Support
quickemu performs automatic hardware detection to provide the best performance. Key feature support includes:
- Acceleration: VirGL acceleration for graphics.
- Storage/Sharing: VirtIO-webdavd (Linux/Windows), VirtIO-9p (Linux/macOS), and Samba (cross-platform).
- Peripheral Integration: USB device pass-through, Smartcard pass-through, and Braille support.
- Networking: Automatic SSH port forwarding and general network port forwarding.
- Firmware: EFI (with or without SecureBoot) and Legacy BIOS support.
Sources: README.md:58-76
Platform and Architecture Support
Quickemu supports a variety of host and guest architectures, adjusting its behavior based on the underlying hardware.
Host and Guest Compatibility
| Entity | Supported Architectures / Platforms |
|---|---|
| Hosts | Linux (x86_64, aarch64), macOS (x86_64, aarch64) |
| Guests | Windows (10, 11, Server), macOS (Sequoia to Mojave), Linux, BSDs, and legacy OSs |
| ARM64 | Native execution on ARM hosts; emulated via TCG on x86_64 hosts |
Sources: README.md:50-57, AGENTS.md:93-98
ARM64 Logic Flow
When running aarch64 guests, quickemu switches to specific firmware and machine types to ensure compatibility.
Sources: AGENTS.md:93-100
Development and Contributions
The project follows strict standards to ensure the stability of the launcher.
- Language: Bash 4.0+ is required for both
quickemuandquickget. - Styling:
quickemuuses a 2-space indentation, whilequickgetuses 4 spaces. - Quality Control: All scripts must be ShellCheck compliant.
- Workflow: The project uses Nix flakes for dependency management and environment isolation.
Sources: AGENTS.md:39-50, CONTRIBUTING.md:1-12, CODE_OF_CONDUCT.md:1-10
Security and Maintenance
Quickemu is maintained as a best-efforts hobby project. Security updates are prioritized for the latest stable versions (currently 4.9.x). Users discovering vulnerabilities are encouraged to report them through the GitHub Issues interface using the "Report a vulnerability" template.
Sources: SECURITY.md:1-15
Quickemu simplifies the complex task of VM management by abstracting QEMU's complexity into a streamlined, hardware-aware launcher. By utilizing optimized defaults and automated configuration, it serves as a powerful tool for developers and testers across Linux and macOS environments.