Skip to main content

Installation

qqX - Quickemu Virtual Machine Manager​

qqX should run on the vast majority of Linux distributions without problems

  • Other virtual machine systems may be present on the host but they are not required

  • Existing Quickemu/QuickGui installations are fully compatible

New users may need to install as little as qemu spice-gtk and qqX

  • Existing Quickemu users will probably have the key dependencies installed already

Generally, no further software or dependencies should be needed but there has been an increasing tendency for individual distros and OS packagers to be dropping small normally present elements from the standard utility tool sets, for example in the case of bc and Arch.

There is also the case where packages that almost everyone normally includes, suddenly start disappearing, or where packages such as curl have been generally adopted but are not present in a one major distribution eg Ubuntu.

  • Some distro versions may need curl 7z jq bc socat and possibly xrandr

As many elements of qqX ultimately front end QuickEmu, it is worth checking the quickemu dependency lists if you run into problems.

All standard TERMINAL emulators should be supported but recent changes to Wayland display systems have yielded a few sudden surprises, as in the case of Gnome 49.

  • There are notes and a list of suitable terminals at the start of the installer script

  • The qqX installer will try to warn you if anything crucial is missing

To create WINDOWS Virtual machines, you will also need swtpm and some distros may also need mkisofs

  • See further notes towards the end of this help file

Linux standards​

Users of non-standard OS's such as NixOS, should read issue #1 and details on Filesystem Hierarchy Standards

  • Further notes are in the installer script.

  • Running qqX on Windows hosts has been partly implemented already via the Windows Linux Subsystem. This target will hopefully be possible when the new and even more capable Azure 3 WSL becomes mainstream. It should be noted that Microsoft, who not only host GitHub, have been Platinum members of the Linux Foundation for several years and that Linux now runs on the majority their Azure cloud servers. Early work with pre-release versions, in Windows Insider, has shown good promise.

  • Basic support is available via Quickemu on MacOS hosts. However, for qqX, unless Mac change their stance towards Linux, this would need impossible code compromises.

Qemu​

Qemu may be listed with various names:

  • Arch users should install 'qemu-desktop' not qemu-base.

  • Debian based distros may need several separate components to create the packages

Some users may see Qemu listed by architecture as in qemu-system-x86_64 and qemu-system-aarch64

  • Only 'x86_64' is needed unless you wish to emulate Arm etc ...

Spice​

Spice gtk may be listed as spice-client-gtk

Newer Ubuntu releases may need qemu-system-modules-spice

qqX Installation​

Downloading​

The standard download method is via the latest qqX release which will have been carefully tested.

The main branch may also contain occasional updates. These will be noted at the head of the 'latest release' page and are usually minor tweaks or additions that need little testing but might be useful. Small pre-release urgent fixes may also be present.

release-updates

For branch downloads, select the required branch, click on the 'code' button and 'download zip'.

  • The normally present dev-next branch is usually fairly stable but may be incomplete and may not have been fully tested

  • Other branches, if present, may have experimental features or bug fixes

Check the branch commits list before downloading

qqX-releases-folder

  • Default Folders for the updater are ~/Downloads/qqX.releases and .../VMQs/qqX.releases but others may be used.

Unpacking the compressed file​

FOR MOST USAGE CASES

  • Simply right clicking in a file manager and selecting extract or extract with ....

For the Cmd Line, see notes further on

Running the installer​

In many file managers you can usually right click, then run as program, or similar.

  • With Cinnamon and Mate, double click and 'run in terminal'

mate-open-t

  • In KDE/Dolphin, use 'run in konsole' or double click and execute.

  • Also with Thunar, if the run scripts preference has been set.

installer-menu-kde-konsole-8

In other environments it may be necessary to start the installer script by opening a terminal first.

  • In the file-manager folder > right click > open in terminal > type ./qqX_setup_and_install ~ note prefix ./

Default VM folder​

  • If you have existing quickemu virtual machines, start qqX and edit the settings file to point to where they are.

    vmq-folder

  • 'VMQs' is the standard default, in your Home folder, next to Downloads & Videos.

  • Moving or renaming the default folder can be easily done using your file manager. Start qqX and edit the settings to point to it.

First Machines​

If everything appears to be working correctly, you can start exploring ...

  • Installing a basic or familiar Linux distro will help tell you if Qemu and the sub-structure is working.

Updates​

An auto-detector will tell you if new a qqX release is available.

  • The qqX installer can be used to update, reinstall, uninstall or reconfigure.

Other Notes​

Cmd Line​

For non-gui installation, create a qqX.releases folder and a subfolder numbered as per the release. Move the tar.gz file into the subfolder and extract as so:

mkdir -p "$HOME/Downloads/qqX.releases/1.11.04"

mv qqX-1.11.04.tar.* "$HOME/Downloads/qqX.releases/1.11.04/"

cd "$HOME/Downloads/qqX.releases/1.11.04"

sha256sum -c qqX-1.11.04.tar.gz.sha256
qqX-1.11.04.tar.gz: OK

tar xvfz qqX-1.11.04.tar.gz

Adjusting the terminal​

qqX will test and setup most standard desktop associated terminals without problem.

To MANUALLY SPECIFY the terminal name, the installer script's 'UserTerm' variable may be edited.

  • Open the script in a standard text editor. From Version 1.11 this is located at the start of the script.

From qqX version 1.10.02 onwards, a 'CustomTerminalProfile' will now be stored in the qqX settings folder. This file will be checked and auto-read when carrying out updates. The (hidden) file '$HOME/.qqX/qqX_term.conf' may also be edited.

MAKE SURE to SELECT option [r] reconfigure desktop launcher during installation, if changing the terminal command

Profile options​

It is quite common for different distros to rename or tweak a standard terminal. Typing the terminal name, followed by '--help' should give you a list of the parameters that you can use. Note that options can vary slightly and can also be subject to theming or desktop environment overrides.

For actual 'XTERM' itself, also edit the installer script's 'CustomTerminalProfile' eg xterm -geometry 145x50 -fa truetype -fs 12

For CUSTOM PROFILES, only one profile line is required and the actual sizes are best stated. Auto-updating size variable lines are difficult to set, due to 'escaping' routines, but may be initially be copied, if wished. Size variables will eventually become overwritten as numerics.

eg. CustomTerminalProfile=" --geometry=145x50 --hide-menubar --title=qqX "

Remember that width and height are normally column/row units which are based on the size of your terminal font and that the window size will alter when the font size is changed.

  • CUSTOM terminal sizes & profile may be initially set just after the initial system checking lines, at around line 290 in the target script "./qqX_system_install" in the qqX.system folder. See notes in the target script.

  • OR may be adjusted in the qqX config file following initial setup, which is possibly easier.

Tips​

If you you are finding the interface a bit cramped, re-run the installer. Make sure to run the desktop part which will allow you to adjust the terminal size.

Multiple folders can help organise your distros. After adding a new group folder, make sure that it's present in the general settings file.

Virtual machines can be easily moved around. Use the move and rename tool [mv] to make things even easier. Make sure that they have their .conf file next to them and make sure the config internals point correctly.

You can edit which VMs to show first in the general settings.

Uninstalling​

  • Re-run the installer and select to remove ...

  • To downgrade, using the installer from an earlier release will normally work without the the need to uninstall first.

Further notes are in the installer script itself.

Other Software​

  • 7z is sometimes listed as 7zip or p7zip-full and xrandr may sometimes be found as part of x11-xserver-utils

  • Fedora does not have Zsync but this is non-critical as Quickget will switch to using Curl

  • On Solus, quickemu won't currently run in UEFI mode, so no Windows 11 for now. See this Solus issue.

  • Support for SDL with OpenSUSE is patchy at best

  • Grabbing https://software.opensuse.org/package/SDL3 and https://software.opensuse.org/package/qemu-ui-sdl might work with certain versions > Select the file and open in Yast, then search sdl with the files option selected ...

  • Immutable/atomic systems may not allow installations ....

Mk ISO FS​

A lot of distros will already have mkisofs already installed as a dependency to other software. Ubuntu installs this with the genisoimage package. Arch users will usually need to add cdrtools. Fedora Gnome should have this already but Fedora KDE will require xorriso. Others may require cdrkit.

This is currently only needed to assemble the Spice unattended Iso, used for setting up Windows VMs.

TPM​

This is needed for Ubuntu Server and for installing Windows guests

Ubuntu 24.04 LTS at 01/2025 is three versions behind for swtpm

There is an on-going swtpm / apparmor problem too. Your mileage may vary.

  • One way to fix this is to change swtpm settings from 'enforce' mode to 'complain'. See these apparmor notes.

Simplified GUI installers such as Gnome Software and KDE Discover may not list swtpm

Command line use of apt or dnf etc may be needed

Also see the Windows Walk-thru guide for notes on Secure Boot

Older or LTS distros​

Some distros can be a long way behind the curve and older QEMU versions may show occasional error messages.

  • Ubuntu 22.04 can show gui-module ui-ui errors but tests seem to show these can be ignored.

Finally​

By using this software you become a valued member of the community and can help make this software better for others.

Please report any difficulties or any unnoticed errors you may have encountered.