Creating Windows Virtual Machines
Relevant source files
The following files were used as context for generating this wiki page:
Quickemu provides a streamlined workflow for creating and running optimized Windows virtual machines on Linux and macOS hosts. By leveraging the quickget and quickemu utilities, users can automate the retrieval of official Windows media and the generation of performance-tuned QEMU configurations without manual intervention.
The system supports a wide range of Windows versions, including Windows 10, Windows 11 (with TPM 2.0 support), and Windows Server editions. It integrates advanced features such as SPICE for clipboard sharing, VirtIO for high-performance I/O, and QEMU Guest Agent support for system-level management.
Sources: README.md:12-45, AGENTS.md:3-8
Core Architecture and Workflow
The creation of a Windows VM involves two primary components: quickget for asset acquisition and quickemu for execution.
- Asset Acquisition (
quickget): This tool communicates with upstream sources to download the ISO image and automatically generates a.conffile specific to the Windows version and hardware environment. - VM Execution (
quickemu): This component reads the configuration, detects host hardware capabilities, and launches the VM with optimized parameters.
The following diagram illustrates the lifecycle of creating and starting a Windows VM:
The flow demonstrates the transition from initial setup via quickget to the execution phase via quickemu.
Sources: README.md:73-86, AGENTS.md:5-8
Supported Windows Versions and Features
Quickemu includes specific optimizations for modern Windows environments, particularly concerning security requirements and hardware acceleration.
OS Compatibility Table
| OS Type | Supported Versions | Key Hardware Features |
|---|---|---|
| Windows Desktop | Windows 10, Windows 11 | TPM 2.0, EFI/SecureBoot |
| Windows Server | 2016, 2019, 2022 | VirtIO-webdavd, Samba |
Sources: README.md:36-54
Optimization Features
- TPM 2.0 & SecureBoot: Essential for Windows 11 compatibility, handled automatically by the configuration generator.
- VirtIO Drivers: Support for
virtio-webdavdenables seamless file sharing between the host and Windows guests. - Guest Integration: Full SPICE support facilitates host/guest clipboard sharing, while the QEMU Guest Agent provides a communication channel for QMP commands.
- Networking: Automatic SSH port forwarding and general network port forwarding are supported for guest access.
Sources: README.md:46-60, AGENTS.md:65-70
Configuration and Implementation
The implementation relies on Bash scripts that utilize dynamic dispatch to handle different operating systems. For Windows, quickget determines the appropriate download URLs and configuration templates.
Key Components
| Component | Responsibility | Script/Path |
|---|---|---|
| VM Launcher | Main logic for starting VMs and detecting hardware. | quickemu |
| OS Downloader | Logic for ISO retrieval and config generation. | quickget |
| Firmware | UEFI support via OVMF (x86_64) or AAVMF (ARM64). | AGENTS.md:73-75 |
| TPM | Software TPM emulation using swtpm. | AGENTS.md:73 |
Sources: AGENTS.md:5-15, AGENTS.md:73-75
Data Flow for VM Launch
When a Windows VM is launched, quickemu performs several checks to ensure the guest is optimized for the host architecture.
This sequence shows how quickemu coordinates between the host environment, the TPM emulator, and the QEMU process to provide a functional Windows environment.
Sources: README.md:46-51, AGENTS.md:65-75
Security and Integrity
Quickemu includes utilities to ensure the integrity of the downloaded Windows media and the security of the virtualization process.
- Download Verification: The
chunkcheckutility is used to verify the integrity of downloaded assets. - Process Security: Virtual machines run without requiring elevated permissions (no
sudorequired), allowing them to be stored in home directories or external storage. - Vulnerability Reporting: Security issues are handled via a dedicated reporting process in the project's issue tracker.
Sources: README.md:27-30, AGENTS.md:7, SECURITY.md:12-18
Development and Contributions
Adding or updating Windows support (e.g., adding a new Windows 11 build) involves modifying quickget. Developers must adhere to specific coding standards:
- Bash 4.0+: All scripts require a modern Bash environment.
- Style: 4-space indentation is used within
quickget. - Commit Format: All changes must follow Conventional Commits.
Sources: AGENTS.md:27-32, AGENTS.md:47-52, CONTRIBUTING.md:10-12
Summary
Creating Windows virtual machines with Quickemu is an automated process that abstracts the complexity of QEMU configuration. By combining quickget for automated ISO management and quickemu for hardware-optimized execution, the project enables high-performance Windows 10, 11, and Server environments. Key features like TPM 2.0, VirtIO, and SPICE are integrated by default, ensuring that Windows guests are both secure and functional on Linux and macOS hosts.
Sources: README.md:12-25, AGENTS.md:3-8