Quick Start Guide
Relevant source files
The following files were used as context for generating this wiki page:
Quickemu is a powerful Bash-based wrapper for QEMU designed to simplify the creation and management of virtual machines. Its primary goal is to automate the complex configuration usually required for QEMU, enabling users to quickly spin up optimized VMs for Linux, macOS, Windows, and various other operating systems without requiring elevated permissions or exhaustive manual setup.
The system is composed of two primary functional components: quickget, which handles the acquisition of operating system images and configuration generation, and quickemu, which performs hardware enumeration and launches the virtual machine with optimized settings. Together, these tools provide a streamlined workflow from OS selection to a running desktop environment.
Sources: README.md:15-32, AGENTS.md:3-8
System Architecture and Workflow
Quickemu operates as a decoupled system where image management and VM execution are handled by distinct utilities. The workflow starts with the user identifying a target OS and ends with a running QEMU instance.
Core Components
| Component | Description |
|---|---|
quickget | Downloads upstream ISO images and generates the .conf file. |
quickemu | Reads configuration, detects host hardware, and executes QEMU. |
quickreport | A diagnostics tool for system information and troubleshooting. |
chunkcheck | A utility used to verify the integrity of downloaded files. |
Sources: AGENTS.md:5-13
Operational Flow
The following diagram illustrates the standard procedure for creating and launching a virtual machine using the Quickemu toolset.
The diagram shows the transition from quickget (fetching resources) to quickemu (launching the environment).
Sources: README.md:84-102, AGENTS.md:5-8
Basic Usage
Getting started with Quickemu involves two primary commands executed in sequence.
1. Downloading and Configuring
Use quickget to fetch the necessary files. Executing quickget without arguments provides a list of all supported operating systems.
quickget nixos unstable minimal
Sources: README.md:90-102
2. Launching the VM
Once the configuration file (e.g., nixos-unstable-minimal.conf) is created, use quickemu to start the machine.
quickemu --vm nixos-unstable-minimal.conf
Sources: README.md:98-100
Supported Platforms and Features
Quickemu supports approximately 1000 operating system editions across various architectures.
Guest Support Matrix
- Windows: 10, 11 (with TPM 2.0 support), and Server (2016, 2019, 2022).
- macOS: Sequoia down to Mojave.
- Linux: Ubuntu and all official flavors, NixOS, and hundreds more.
- Others: BSDs, FreeDOS, Haiku, ReactOS, and OpenIndiana.
- Architectures: x86_64 (default) and aarch64 (native on ARM hosts, emulated on x86_64).
Sources: README.md:34-51, AGENTS.md:75-78
Key Integrated Features
- Sharing: VirtIO-webdavd (Linux/Windows), VirtIO-9p (Linux/macOS), and Samba.
- Hardware: USB and Smartcard pass-through, VirGL acceleration, and Full duplex audio.
- Networking: Automatic SSH and network port forwarding.
- Security: EFI with or without SecureBoot.
Sources: README.md:52-66
Development and Contribution
Quickemu is a community-driven project that follows specific standards for code and conduct.
Environment Setup
For developers using Nix, a development shell is available to ensure all dependencies like ovmf, swtpm, and samba are present.
nix develop
Sources: AGENTS.md:15-20
Contribution Standards
- Code Style: Bash 4.0+ is required. Scripts must be ShellCheck compliant.
- Commits: Must follow the Conventional Commits specification (e.g.,
feat(quickget): add new OS). - Safety: Security vulnerabilities should be reported via the "Report a vulnerability" button in GitHub Issues.
- Community: All participants must adhere to the Contributor Covenant Code of Conduct, which prioritizes a harassment-free experience.
Sources: AGENTS.md:41-65, CONTRIBUTING.md:11-13, SECURITY.md:11-13, CODE_OF_CONDUCT.md:5-15
Summary
Quickemu provides a streamlined, user-space approach to virtualization. By separating the concerns of image acquisition (quickget) and execution (quickemu), it allows for a highly automated experience that optimizes QEMU settings based on the host hardware. This enables developers and testers to deploy complex operating systems like Windows and macOS with minimal manual intervention.