Installation & Prerequisites
Relevant source files
The following files were used as context for generating this wiki page:
Quickemu is a terminal-based tool designed to simplify the creation and operation of highly optimized virtual machines. By acting as a sophisticated wrapper around QEMU, it automates the complex configuration processes typically required for diverse operating systems including Linux, macOS, Windows, and various BSDs.
The system is composed of two primary functional units: quickget, which handles the acquisition of OS images and initial configuration generation, and quickemu, which manages the runtime environment and hardware optimization. This modular approach ensures that users can go from a clean slate to a running VM with minimal manual intervention.
Sources: README.md:14-22, AGENTS.md:3-6
Supported Platforms
Quickemu supports a variety of host and guest architectures. While it is primarily developed for Linux and macOS hosts, it can virtualize or emulate a wide range of guest operating systems.
| Component | Supported Platforms / Architectures |
|---|---|
| Host OS | Linux (x86_64, aarch64), macOS (x86_64, aarch64) |
| Guest OS | Windows (10, 11, Server), macOS (Mojave to Sequoia), Linux (Ubuntu and ~1000 others), BSDs, FreeDOS |
| Guest Arch | x86_64 (default), aarch64 |
| Sources: README.md:31-40, AGENTS.md:95-98 |
Architecture Logic
The following diagram illustrates how Quickemu handles different architecture combinations between the host and the guest.
Cross-architecture emulation (e.g., running aarch64 on x86_64) utilizes TCG and does not benefit from KVM acceleration.
Sources: AGENTS.md:98-100
System Requirements & Dependencies
To function correctly, the host system must meet specific software requirements. Quickemu relies on several external utilities to handle networking, disk imaging, and hardware virtualization.
Core Runtime Dependencies
The project requires Bash 4.0 or higher. The scripts perform an explicit version check at runtime to ensure compatibility.
Sources: AGENTS.md:101-101, AGENTS.md:43-43
Dependency Matrix
The following tools must be present on the host system for full functionality:
| Dependency | Purpose | Requirement |
|---|---|---|
qemu | Core virtualization engine | Mandatory |
curl | Downloading ISO images via quickget | Mandatory |
jq | Processing JSON data for OS metadata | Mandatory |
cdrtools | Generating ISO/disk metadata | Mandatory |
spice-gtk | Enhanced display and clipboard sharing | Optional (Recommended) |
swtpm | TPM 2.0 support (required for Windows 11) | Optional |
samba | File sharing between host and guest | Optional |
ovmf / aavmf | UEFI firmware for guest booting | Mandatory (Linux hosts) |
| Sources: AGENTS.md:103-106, README.md:52-53 |
Development Environment Setup
For contributors looking to modify the source or test new features, Quickemu provides a Nix-based development environment. This ensures that all linting and testing tools are available without polluting the host system.
Nix Integration
The repository includes several files for Nix support:
flake.nix: The primary Nix flake definition.package.nix: Defines the Quickemu package.devshell.nix: Configures the development shell.
To enter the development environment, use:
nix develop
This shell automatically patches quickemu to use Nix store paths for specific dependencies like OVMF and Samba.
Sources: AGENTS.md:11-20
Quality Assurance Tools
Contributors are expected to validate their changes using the following tools before submission:
- ShellCheck: Used for linting Bash scripts (
quickemu,quickget,quickreport,chunkcheck). - Conventional Commits: Commit messages must follow the standard format (e.g.,
feat(quickget): ...orfix(quickemu): ...).
Sources: AGENTS.md:23-24, AGENTS.md:65-70, CONTRIBUTING.md:10-11
Deployment Workflow
The standard installation and usage flow follows a two-step process to ensure the VM is optimized for the detected hardware.
Sources: README.md:83-95, AGENTS.md:3-6
Summary
Quickemu simplifies the complex ecosystem of QEMU by providing a streamlined installation and execution path. By satisfying the core dependencies (primarily QEMU, Bash 4.0+, and specific firmware like OVMF), users can leverage automated downloads via quickget and hardware-optimized execution via quickemu. For developers, the project enforces strict coding standards through ShellCheck and provides a reproducible environment via Nix flakes.
Sources: README.md:14-22, AGENTS.md:103-106, CODE_OF_CONDUCT.md:35-39