diff --git a/README.md b/README.md
index 7c5bd7bd7b..66b8ce4b7e 100644
--- a/README.md
+++ b/README.md
@@ -1,31 +1,75 @@
-
- 
-
- Quickemu
-
+
-
Quickly create and run optimised Windows, macOS and Linux desktop virtual machines.
-
-
Made with 💝 for 
+
-## Introduction
+# Quickemu
-Quickly create and run highly optimised desktop virtual machines for
-Linux, macOS and Windows; with just two commands. You decide what
-operating system you want to run and Quickemu will figure out the best
-way to do it for you. For example:
+**Quickly create and run optimised Windows, macOS and Linux desktop virtual machines:**
-``` bash
+
+
+
+
+**Made with 💝 for
.**
+
+Quickemu is available in the repositories of the following distros
+(packaging status by [Repology.org](https://repology.org/)):
+
+
+
+
+|
+
+[](https://repology.org/project/quickemu/versions)
+
+ |
+
+
+[](https://repology.org/project/quickgui/versions)
+
+ |
+
+
+
+
+We have a Discord for this project:
+
+[](https://discord.gg/sNmz3uw)
+
+
+
+[](https://www.youtube.com/watch?v=AOTYWEgw0hI)
+
+
## Features
@@ -52,20 +96,70 @@ Windows**.
- EFI (with or without SecureBoot) and Legacy BIOS boot
- Graphical user interfaces available
-Quickemu is a wrapper for the excellent [QEMU](https://www.qemu.org/)
-that attempts to automatically *"do the right thing"*, rather than
-expose exhaustive configuration options.
+## Installation
-We have a Discord for this project:
-[](https://discord.gg/sNmz3uw)
+### Arch Linux hosts
-See this (old) video where I explain some of my motivations for creating
-Quickemu.
+Quickemu is available from the AUR (Arch user repository), and can be
+installed via any AUR helper. Assuming your AUR helper is yay, Run the
+following command:
-[](https://www.youtube.com/watch?v=AOTYWEgw0hI)
+``` bash
+yay -Sy quickemu
+```
+
+### Ubuntu hosts
+
+Quickemu is available from a PPA for Ubuntu users. The Quickemu PPA also
+includes a back port of QEMU 6.0.0 for 20.04 (Focal) and 21.04
+(Hirsute). To install Quickemu and all the dependencies run the
+following in a terminal:
+
+``` bash
+sudo apt-add-repository ppa:flexiondotorg/quickemu
+sudo apt update
+sudo apt install quickemu
+```
+
+### NixOS hosts
+
+To quickly try quickemu:
+
+```sh
+nix-shell -p quickemu
+```
+
+To install via Nix profile:
+
+```sh
+nix-env -iA pkgs.quickemu
+```
+
+To install via NixOS config:
+
+```nix
+# /etc/nixos/configuration.nix
+{pkgs, ...}: {
+ environment.systemPackages = with pkgs;
+ quickemu
+ };
+}
+```
+
+To install via Flakes:
+
+```sh
+# TODO (flake users, please add an example!)
+```
+
+### Other Linux hosts (installing from source)
+
+``` bash
+git clone --filter=blob:none https://github.com/wimpysworld/quickemu
+cd quickemu
+```
-## Requirements
+When installing from source, you will need to install the following requirements manually:
- [QEMU](https://www.qemu.org/) (*6.0.0 or newer*) **with GTK, SDL,
SPICE & VirtFS support**
@@ -91,9 +185,7 @@ QEMU](https://img.youtube.com/vi/AOTYWEgw0hI/0.jpg)](https://www.youtube.com/wat
- [zsync](http://zsync.moria.org.uk/)
- [unzip](http://www.info-zip.org/UnZip.html)
-### Installing Requirements
-
-For Ubuntu, Arch and nixos systems the
+For Ubuntu, Arch and NixOS hosts, the
[ppa](https://launchpad.net/~flexiondotorg/+archive/ubuntu/quickemu),
[AUR](https://aur.archlinux.org/packages/quickemu) or
[nix](https://github.com/NixOS/nixpkgs/tree/master/pkgs/development/quickemu)
@@ -101,109 +193,65 @@ packaging will take care of the dependencies. For other host
distributions or operating systems it will be necessary to install the
above requirements or their equivalents.
-These examples may save a little typing
+These examples may save a little typing:
-Debian (and direct derivatives such as MX Linux):
+#### Install requirements on Debian hosts
- sudo apt install qemu bash coreutils ovmf grep jq lsb-base procps python3 genisoimage usbutils util-linux sed spice-client-gtk libtss2-tcti-swtpm0 wget xdg-user-dirs zsync unzip
+This also applies to direct derivatives, such as MX Linux:
-Fedora:
+```sh
+sudo apt install qemu bash coreutils ovmf grep jq lsb-base procps python3 genisoimage usbutils util-linux sed spice-client-gtk libtss2-tcti-swtpm0 wget xdg-user-dirs zsync unzip
+```
- sudo dnf install qemu bash coreutils edk2-tools grep jq lsb procps python3 genisoimage usbutils util-linux sed spice-gtk-tools swtpm wget xdg-user-dirs xrandr unzip
+#### Install requirements on Fedora hosts
-MacOS:
+```sh
+sudo dnf install qemu bash coreutils edk2-tools grep jq lsb procps python3 genisoimage usbutils util-linux sed spice-gtk-tools swtpm wget xdg-user-dirs xrandr unzip
+```
-This is a work in progress (see [issue
-248](https://github.com/quickemu-project/quickemu/issues/248) for other
-steps and changes that may enable running on MacOS)
+#### Install requirements on macOS hosts
- brew install qemu bash coreutils grep jq python@3.10 cdrtools gnu-sed spice-gtk wget zsync
+This is a work in progress (see [issue 248](https://github.com/quickemu-project/quickemu/issues/248)
+for other steps and changes that may enable running on MacOS)
-# Usage
+```sh
+brew install qemu bash coreutils grep jq python@3.10 cdrtools gnu-sed spice-gtk wget zsync
+```
-## Graphical User Interfaces
+## GUI (quickgui)
While `quickemu` and `quickget` are designed for the terminal, a
graphical user interface is also available:
-- **[Quickgui](https://github.com/quickgui/quickgui)** by [Mark
- Johnson](https://github.com/marxjohnson) and [Yannick
- Mauray](https://github.com/ymauray).
+- **[Quickgui](https://github.com/quickgui/quickgui)** by [Mark Johnson](https://github.com/marxjohnson) and [Yannick Mauray](https://github.com/ymauray).
-Many thanks to [Luke Wesley-Holley](https://github.com/Lukewh) and
-[Philipp Kiemle](https://github.com/daPhipz) for creating the
-**[Quickemu icons](https://github.com/Lukewh/quickemu-icons)** 🎨
+To install Quickgui on Ubuntu:
-### Quickgui for Ubuntu
-
-``` bash
+```sh
sudo add-apt-repository ppa:yannick-mauray/quickgui
sudo apt update
sudo apt install quickgui
```
-### quickemu quickget X terminal project
+Many thanks to [Luke Wesley-Holley](https://github.com/Lukewh) and
+[Philipp Kiemle](https://github.com/daPhipz) for creating the
+**[Quickemu icons](https://github.com/Lukewh/quickemu-icons)** 🎨
+
+## TUI (qqx)
From Nov 2023, there is also a multi option desktop integrated text
-interface, with lots of unique tools and utilities to help you make
+interface, the **quickemu quickget X terminal project**, a.k.a. **qqX**,
+with lots of unique tools and utilities to help you make
light work of installations, snapshots and disk management
-- **[qqX](https://github.com/TuxVinyards/qqX)** is independently
- curated by [Alex Genovese](https://github.com/TuxVinyards) (see the
- github pages)
+- **[qqX](https://github.com/TuxVinyards/qqX)** is independently curated
+ by [Alex Genovese](https://github.com/TuxVinyards) (see the github pages)
-# Install Quickemu
+## Creating Linux guests 🐧
-## Arch
-
-Quickemu is available from the AUR (Arch user repository), and can be
-installed via any AUR helper. Assuming your AUR helper is yay, Run the
-following command:
-
-``` bash
-yay -Sy quickemu
-```
-
-## Ubuntu
-
-Quickemu is available from a PPA for Ubuntu users. The Quickemu PPA also
-includes a back port of QEMU 6.0.0 for 20.04 (Focal) and 21.04
-(Hirsute). To install Quickemu and all the dependencies run the
-following in a terminal:
-
-``` bash
-sudo apt-add-repository ppa:flexiondotorg/quickemu
-sudo apt update
-sudo apt install quickemu
-```
-
-## Other Linux
-
-``` bash
-git clone --filter=blob:none https://github.com/wimpysworld/quickemu
-cd quickemu
-```
-
-Now install all the **Requirements** documented above.
-
-### Other sources
-
-[Repology.org](https://repology.org/) found the following releases have
-been packaged.
-
-#### Quickemu
-
-[](https://repology.org/project/quickemu/versions)
-
-#### Quickgui
-
-[](https://repology.org/project/quickgui/versions)
-
-## Ubuntu Guest
+### Ubuntu
`quickget` will automatically download an Ubuntu release and create the
virtual machine configuration.
@@ -269,7 +317,7 @@ The `--show-iso-url` and `--test-iso-url` options **do not** work for
`Windows` (`quickget` will begin downloading the requested release and
edition of windows)
-## Other Operating Systems
+### Other Operating Systems
`quickget` also supports:
@@ -338,6 +386,8 @@ edition of windows)
- `xerolinux` (XeroLinux)
- `zorin` (Zorin OS)
+### Custom Linux guests
+
Or you can download a Linux image and manually create a VM
configuration.
@@ -363,7 +413,7 @@ quickemu --vm debian-bullseye.conf
- Install the SPICE WebDAV agent (`spice-webdavd`) in the guest to
enable file sharing.
-## macOS Guest
+## Creating macOS Guests 🍏
`quickget` automatically downloads a macOS recovery image and creates a
virtual machine configuration.
@@ -509,16 +559,16 @@ sudo rm /Library/Preferences/SystemConfiguration/NetworkInterfaces.plist
Now reboot, and the App Store should work.
-## Windows 8, 10 & 11 Guests
+## Creating Windows guests 🪟
`quickget` can download
-[Windows10](https://www.microsoft.com/software-download/windows10) and
-[Windows 11](https://www.microsoft.com/software-download/windows11)
+[**Windows 10**](https://www.microsoft.com/software-download/windows10) and
+[**Windows 11**](https://www.microsoft.com/software-download/windows11)
automatically and create an optimised virtual machine configuration.
This configuration also includes the [VirtIO drivers for
Windows](https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/).
-Windows 8.1 is also supported but doesn't feature any automated
+**Windows 8.1** is also supported but doesn't feature any automated
installation or driver optimisation.
``` bash
@@ -549,7 +599,9 @@ secureboot="off"
- `tpm="on"` instructs `quickemu` to create a software emulated TPM
device using `swtpm`.
-# SPICE
+## Connecting to your VM
+
+### SPICE
The following features are available while using the SPICE protocol:
@@ -568,7 +620,7 @@ quickemu --vm ubuntu-22.04.conf --display spice
To enable copy/paste with a Windows guest, install [SPICE Windows guest
tools](https://www.spice-space.org/download.html) in the guest VM.
-## Headless
+### Headless
To start a VM with SPICE enabled, but no display attached use
`--display none`. This requires that the `spicy` client is installed,
@@ -594,7 +646,7 @@ it from the host as follows:
ssh -p 22220 your_vm_user@localhost
```
-# Accessibility
+### Accessibility
Qemu provides support for using BrlAPI to display braille output on a
real or fake device.
@@ -603,7 +655,7 @@ real or fake device.
quickemu --vm ubuntu-22.04.conf --braille --display sdl
```
-# BIOS and EFI
+### BIOS and EFI
Since Quickemu 2.1.0 `efi` is the default boot option. If you want to
override this behaviour then add the following line to you VM
@@ -611,7 +663,7 @@ configuration to enable legacy BIOS.
- `boot="legacy"` - Enable Legacy BIOS boot
-# Tuning CPU cores, RAM & disks
+### Tuning CPU cores, RAM & disks
By default, Quickemu will calculate the number of CPUs cores and RAM to
allocate to a VM based on the specifications of your host computer. You
@@ -626,7 +678,7 @@ Add additional lines to your virtual machine configuration:
- `disk_size="16G"` - Specify the size of the virtual disk allocated
to the VM
-## Disk preallocation
+### Disk preallocation
Preallocation mode (allowed values: `off` (default), `metadata`,
`falloc`, `full`). An image with preallocated metadata is initially
@@ -638,14 +690,14 @@ configuration.
- `preallocation="metadata"`
-## CD-ROM disks
+### CD-ROM disks
If you want to expose an ISO image from the host to guest add the
following line to the VM configuration:
- `fixed_iso="/path/to/image.iso"`
-## Floppy disks
+### Floppy disks
If you're like [Alan Pope](https://popey.com) you'll probably want to
mount a floppy disk image in the guest. To do so add the following line
@@ -653,12 +705,12 @@ to the VM configuration:
- `floppy="/path/to/floppy.img"`
-# File Sharing
+### File Sharing
All File Sharing options will only expose `~/Public` (or localised
variations) for the current user to the guest VMs.
-## Samba 🐧 🍏 🪟
+#### Samba 🐧 🍏 🪟
If `smbd` is available on the host, Quickemu will automatically enable
the built-in QEMU support for exposing a Samba share from the host to
@@ -679,15 +731,17 @@ If using a Windows guest, right-click on "This PC", click "Add a network
location", and paste this address, removing `smb:` and replacing forward
slashes with backslashes (in this example `\\10.0.2.4\qemu`).
-## SPICE WebDAV 🐧 🪟
+#### SPICE WebDAV 🐧 🪟
- TBD
-## VirtIO-9P 🐧 🍏
+#### VirtIO-9P 🐧 🍏
- TBD
-# Network port forwarding
+### Networking
+
+#### Port forwarding
Add an additional line to your virtual machine configuration. For
example:
@@ -699,14 +753,14 @@ In the example above:
- Port 8123 on the host is forwarded to port 8123 on the guest.
- Port 8888 on the host is forwarded to port 80 on the guest.
-# Disable networking
+#### Disable networking
To completely disable all network interfaces in a guest VM add this
additional line to your virtual machine configuration:
- `network="none"`
-# Restricted networking
+#### Restricted networking
You can isolate the guest from the host (and broader network) using the
restrict option, which will restrict networking to just the guest and
@@ -718,7 +772,7 @@ additional line to your virtual machine configuration:
- `network="restrict"`
-# Bridged networking
+#### Bridged networking
Connect your virtual machine to a preconfigured network bridge. Add an
additional line to your virtual machine configuration:
@@ -734,19 +788,35 @@ So you can generate your own MAC addresses with:
- `macaddr="52:54:00:AB:51:AE"`
-# USB redirection
+### USB redirection
Quickemu supports USB redirection via SPICE pass-through and host
pass-through.
-## SPICE redirection (recommended)
+#### SPICE redirection (recommended)
Using SPICE for USB pass-through is easiest as it doesn't require any
-elevated permission, start Quickemu with `--display spice` and then
-select `Input` -\> `Select USB Device for redirection` from the menu to
+elevated permission:
+
+* Start Quickemu with `--display spice` and then
+* select `Input` -\> `Select USB Device for redirection` from the menu to
choose which device(s) you want to attach to the guest.
-## Host redirection **NOT Recommended**
+##### Enabling SPICE redirection on NixOS
+
+On NixOS, if you encounter this error:
+
+```
+Error setting facl: Operation not permitted
+```
+
+Try setting [the following option](https://search.nixos.org/options?channel=23.11&show=virtualisation.spiceUSBRedirection.enable&from=0&size=50&sort=relevance&type=packages&query=spiceusbredirec):
+
+```nix
+virtualisation.spiceUSBRedirection.enable = true;
+```
+
+#### Host redirection (**NOT Recommended**)
**USB host redirection is not recommended**, it is provided purely for
backwards compatibility to older versions of Quickemu. Using SPICE is
@@ -773,14 +843,14 @@ like this:
sudo chown -v root:user /dev/bus/usb/001/005
ERROR! USB permission changes are required 👆
-# TPM
+### TPM
Since Quickemu 2.2.0 a software emulated TPM device can be added to
guest virtual machines. Just add `tpm="on"` to your VM configuration.
`quickget` will automatically add this line to Windows 11 virtual
machines.
-# All the options
+## Configuration
Here are the usage instructions:
@@ -897,7 +967,7 @@ which will override system default screen sizes. The VM size will be
'pct' of the chosen screen. **If --fullscreen is chosen screen will be
fullsize instead of being scaled down by --screenpct value.**
-# References
+## References
Useful reference that assisted the development of Quickemu.