DOCSEARCHbyAlgolia
Submit Docs

Quickemu

repository·master·Indexed 12 days ago

https://github.com/quickemu-project/quickemu

A wrapper for QEMU designed to quickly create and run optimized virtual machines for Windows, macOS, and Linux with minimal manual configuration. It includes `quickget` for automated OS downloads and configuration generation, and `quickemu` for launching VMs. Features include support for ARM64 guests, SPICE for USB redirection, automated TPM 2.0 for Windows 11, and OpenCore integration for macOS guests.

Tokens
16.2K
Snippets
52
Records
57
Agent score
93%

What's inside Quickemu

  1. Overview of Quickemu features

    master

    Quickemu is a wrapper for QEMU that automates the configuration of optimized virtual machines.

    Core Capabilities:

    • Automated Setup: quickget handles upstream OS downloads and config generation; quickemu optimizes hardware settings automatically.
    • OS Support: Extensive support for Linux (including Ubuntu flavors), macOS (Sequoia through Mojave), Windows (10, 11 with TPM 2.0, and Server editions), BSDs, and others like FreeDOS and ReactOS.
    • Architecture: Supports ARM64 guests (native on ARM hosts, emulated on x86_64).
    • Host Support: Runs on Linux and macOS.

    Key Features:

    • File Sharing: VirtIO-webdavd (Linux/Windows), VirtIO-9p (Linux/macOS), and Samba (if smbd is installed on host).
    • Hardware/Peripherals: USB device pass-through, Smartcard pass-through, Braille support, and VirGL acceleration.
    • Networking: Automatic SSH port forwarding and general network port forwarding.
    • Display/Audio: Full SPICE support (including clipboard sharing) and full duplex audio.
    • Boot Modes: EFI (with/without SecureBoot) and Legacy BIOS.

  2. macOS guest compatibility and optimizations

    master

    Quickemu provides several optimizations for macOS guests, though GPU acceleration is not available.

    Key Features & Optimizations:

    • Bootloader: Automatically downloads OpenCore and OVMF firmware.
    • CPU: Detects host CPU vendor and optimizes the guest accordingly.
    • Storage: Uses VirtIO Block Media where supported (Catalina and newer).
    • Mouse: Uses VirtIO usb-tablet.
    • Networking: Uses virtio-net on Big Sur and newer; uses vmxnet3 on earlier versions.
    • Memory: VirtIO Memory Ballooning is enabled on Big Sur and newer.
    • USB: Uses XHCI (USB 3.0) on Big Sur and newer; uses UHCI (USB 2.0) on Catalina and earlier.
    • Display: Resolution can be adjusted via CLI using --width and --height.
    • Audio: Full Duplex audio requires VoodooHDA OC or passing through a USB audio device. Note that installing VoodooHDA OC requires disabling Gatekeeper and System Integrity Protection (SIP).
    • File Sharing: Supported via virtio-9p and SPICE webdavd.

    Limitations:

    • Copy/paste via SPICE agent is not available on macOS.

  3. Quickstart: Create and run a virtual machine

    master

    Quickemu uses a two-step process to manage virtual machines. First, use quickget to download the operating system ISO and generate a configuration file. Second, use quickemu to launch the VM using that configuration file.

    To see a list of all supported operating systems, run quickget without any arguments.

    # 1. Download OS and create configuration
quickget nixos unstable minimal

# 2. Start the virtual machine
quickemu --vm nixos-unstable-minimal.conf

  4. Use USB Redirection via SPICE (Recommended)

    master

    To pass USB devices from the host to the guest without requiring elevated permissions, use SPICE redirection:

    1. Start Quickemu with the --display spice flag.
    2. Use a SPICE-compatible viewer:
      • spicy (default): Select Input -> Select USB Device for redirection.
      • remote-viewer: Select File -> USB device selection.
    3. Ensure SPICE Guest Tools are installed in the guest VM.

    NixOS Users: If you encounter Error setting facl: Operation not permitted, enable virtualisation.spiceUSBRedirection.enable = true; in your NixOS configuration.

    virtualisation.spiceUSBRedirection.enable = true;

  5. Create Windows 10 or 11 guests

    master

    You can use quickget to automatically download and configure optimized virtual machines for Windows 10 and Windows 11. These configurations include VirtIO drivers for Windows.

    Automated Setup Details:

    • Drivers: VirtIO drivers are included automatically.
    • User Account: A local administrator account is created automatically with the following credentials:
      • Username: Quickemu
      • Password: quickemu

    Supported Versions:

    • Windows 10 & 11: Fully automated installation and driver optimization.
    • Windows 8.1: Supported, but lacks automated installation/optimization.
    • Windows Server (2012-r2, 2016, 2019, 2022) & Windows 10 LTSC: Supported via quickget, but no automated installation is provided.
    quickget windows 11
quickemu --vm windows-11.conf

  6. Install quickemu requirements on Debian hosts

    master

    For Debian-based systems (earlier versions than Trixie), install the necessary dependencies using apt-get:

    sudo apt-get install bash coreutils curl genisoimage grep jq mesa-utils ovmf pciutils procps python3 qemu sed socat spice-client-gtk swtpm-tools unzip usbutils util-linux xdg-user-dirs xrandr zsync
    sudo apt-get install bash coreutils curl genisoimage grep jq mesa-utils ovmf pciutils procps python3 qemu sed socat spice-client-gtk swtpm-tools unzip usbutils util-linux xdg-user-dirs xrandr zsync

  7. Create custom Linux guests manually

    master

    If a distribution is not supported by quickget, you can manually create a VM configuration file.

    Steps:

    1. Download a .iso image of the Linux distribution.
    2. Create a .conf file (e.g., debian-bullseye.conf) with the following structure:
      • guest_os="linux" (Use guest_os="linux_old" for distros from 2016 or earlier to enable vmware-svga graphics).
      • disk_img="<path-to-qcow2>"
      • iso="<path-to-iso>"
    3. Start the VM: quickemu --vm <your-config>.conf.
    4. Post-install, install spice-vdagent and spice-webdavd for enhanced functionality.
    guest_os="linux"
disk_img="debian-bullseye/disk.qcow2"
iso="debian-bullseye/firmware-11.0.0-amd64-DVD-1.iso"

# To run:
quickemu --vm debian-bullseye.conf

  8. Create macOS guests

    master

    QuickEmu can automatically download macOS recovery images and create configurations.

    Supported Releases: mojave, catalina, big-sur, monterey, ventura, and sonoma.

    Setup Process:

    1. Run quickget macos <release> (e.g., quickget macos big-sur).
    2. Start the VM: quickemu --vm macos-<release>.conf.
    3. Disk Utility Setup:
      • Select QEMU HARDDISK Media (or Apple Inc. VirtIO Block Device for Big Sur+).
      • Click Erase.
      • For Mojave or later, use APFS as the filesystem.
    4. Installation:
      • Click Reinstall macOS and follow prompts.
      • Use cursor keys/Enter to select the macOS Base System and the target disk during reboots.

    Note on VPNs: Some users may need to toggle their VPN to successfully download recovery images.

    Enabling TRIM (Optional): To allow QuickEmu to shrink the macOS disk image when files are deleted, run this inside the macOS guest terminal: sudo trimforce enable Warning: This tool force-enables TRIM and may result in data loss if used in a commercial/critical environment. It will trigger an automatic reboot.

    quickget macos big-sur
quickemu --vm macos-big-sur.conf

  9. Enable File Sharing via Samba

    master

    Quickemu automatically enables Samba sharing if smbd is installed on the host. This exposes the host's ~/Public directory to the guest.

    1. Install Samba (on Ubuntu): sudo apt install --no-install-recommends samba.
    2. Start the VM. The smbd address will be printed (e.g., smb://10.0.2.4/qemu).
    3. In a Windows guest, map a network location using the address with backslashes (e.g., \\10.0.2.4\qemu).
    sudo apt install --no-install-recommends samba

  10. Install Quickgui on Ubuntu

    master

    Quickgui is a graphical user interface for Quickemu. To install it on Ubuntu, use the following commands:

    sudo add-apt-repository ppa:yannick-mauray/quickgui
sudo apt update
sudo apt install quickgui
    sudo add-apt-repository ppa:yannick-mauray/quickgui
sudo apt update
sudo apt install quickgui

  11. Enable TRIM for macOS guests to shrink disk images

    master

    By default, macOS disk images (.qcow2) only grow and do not shrink when files are deleted inside the VM. To allow QuickEmu to compact the disk image, you must enable the TRIM feature inside the macOS guest.

    Warning: Enabling TRIM can result in unintended data loss or corruption. Back up your data before proceeding. This is not recommended for commercial environments.

    Steps to enable TRIM:

    1. Open the Terminal application inside the macOS guest.
    2. Run the following command: sudo trimforce enable
    3. Follow the prompts: type y and press <Enter> for both confirmation questions.
    4. The system will automatically reboot once complete.
    sudo trimforce enable

  12. Use Ubuntu daily-live images

    master

    For developers and testers, quickget supports downloading and refreshing Ubuntu daily-live images via zsync. Running the command again will refresh the image and can automatically switch to a new series.

    Usage:

    quickget ubuntu daily-live
quickemu --vm ubuntu-daily-live.conf