Using quickget (OS Downloader)
Relevant source files
The following files were used as context for generating this wiki page:
quickget is a core Bash script within the Quickemu project designed to automate the acquisition of operating system installation media and the generation of corresponding virtual machine configurations. It serves as the initial step in the Quickemu workflow, handling the complexities of locating upstream ISO images, verifying downloads, and preparing the environment for the quickemu launcher.
The tool supports nearly 1000 operating system editions, including various Linux distributions, macOS versions (from Mojave to Sequoia), Windows (10, 11, and Server), and several BSD and niche operating systems. By abstracting the download and configuration process, quickget enables users to create optimized virtual machines without manual configuration or elevated permissions.
Sources: README.md:14-25, AGENTS.md:5-6, README.md:36-41
Core Functionality and Workflow
The primary purpose of quickget is to fetch a guest OS and generate a .conf file that quickemu can subsequently use to launch the VM. The script interacts with external utilities such as curl for downloading and jq for parsing data, ensuring that the resulting VM is tailored for the specific OS requirements.
Operational Flow
The following diagram illustrates how quickget processes a user request to prepare a virtual machine environment:
The workflow ensures that the ISO is correctly sourced and a configuration file is produced.
Sources: README.md:73-82, AGENTS.md:5-15
Command Line Usage
quickget is invoked with specific arguments to target a distribution, release, and edition. If run without arguments, it provides a comprehensive list of supported operating systems.
Common Commands
| Command | Description |
|---|---|
quickget | Lists all supported operating systems. |
quickget <os> <release> <edition> | Downloads the specified OS and creates a config. |
./quickget --list | Alternative method to list supported OSes. |
./quickget --check <os> [release] | Tests if URLs for a specific OS are still valid. |
./quickget --arch arm64 --check <os> | Tests ARM64 specific download paths. |
Sources: README.md:86-88, AGENTS.md:30-34
Example: Downloading NixOS
quickget nixos unstable minimal
This command downloads the "minimal" edition of the "unstable" release of NixOS and generates nixos-unstable-minimal.conf.
Sources: README.md:76-78
Architecture and Internal Logic
quickget is written in Bash 4.0+ and utilizes dynamic dispatch for many of its functions. This architecture allows it to scale to hundreds of different OS definitions by modularizing the logic required for each distribution.
Configuration Components
For every supported operating system, quickget implements or references several key logic blocks:
os_info(): A case statement that identifies if the requested OS is supported.releases_<os>(): Returns a list of available versions for the distribution.editions_<os>(): Defines sub-variants (e.g., Desktop, Server, XFCE).arch_<os>(): Specifies architecture support; it defaults toamd64unlessarm64is explicitly defined.- Download Construction: Logic to build the final URL for
curlorzsync.
Sources: AGENTS.md:41-55
Dependency Map
The script relies on several system utilities to perform its tasks:
Sources: AGENTS.md:12-13, AGENTS.md:80-82
Advanced Testing and Development
For developers contributing to Quickemu, quickget includes diagnostic modes to ensure that the massive library of OS definitions remains functional.
Testing Utilities
Developers use --check and --check-all-arch flags to validate that upstream download mirrors have not changed or broken. This is a critical part of the CI/CD pipeline, where the test-quickget workflow validates pull requests.
Maintenance and Contribution
When adding a new OS, contributors must follow the Conventional Commits specification. Common prefixes for quickget updates include fix(quickget): for updating existing distributions and feat(quickget): for adding entirely new ones.
Sources: AGENTS.md:30-33, AGENTS.md:58-69, CONTRIBUTING.md:10-12
Summary
quickget is the entry point for the Quickemu ecosystem, automating the tedious process of searching for, downloading, and configuring operating system images. By providing a unified interface for nearly 1000 OS variations and integrating verification tools like chunkcheck, it ensures that users can transition from a command-line request to a running, optimized virtual machine with minimal friction.