Skip to main content

Installation

qqX - Quickemu Virtual Machine Manager​

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

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

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

  • Existing Quickemu/QuickGui installations are fully compatible

qqX has its own BUILT IN INSTALLER AND UPDATER which will let you know if anything needs to done

  • Users may need to install little more than qemu spice-gtk and qqX

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

Example dependency setups:

  • Fedora 43 KDE (2025/11) sudo dnf install xorriso qemu spice-gtk-tools

  • LinuxMint 22.3 Cinnamon (2026/01) sudo apt install jq socat spice-client-gtk qemu-system-x86

The INSTALLER has a further example sets, along with help notes

SHOULD WORK WITH ALL STANDARD LINUX DESKTOPS and window managers and with either X11 or Wayland

  • All standard terminal emulators should be supported, along with recent display innovations

An additional flatpak installer is currently under consideration:

Downloading​

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

qqX-releases-folder

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

From Jan 2026, you may now subscribe to series beta channels. These should be reasonably stable and offer early access to new features. The qqX interface will show muted alerts when beta pre-releases are available

Check the branch commits and the tags list before downloading

release-updates

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

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.

  • Distros will normally support several terminals being installled.

To MANUALLY SPECIFY a terminal name:

  • Open the installer start script in a standard text editor and check near the beginning for the line 'UserTerm'

  • A 'CustomTerminalProfile' is stored in the qqX settings folder and will be auto-read when carrying out updates.

  • The (hidden) file '$HOME/.qqX/qqX_term.conf' may also be edited.

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

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, use the installer from an earlier release, which will normally work without needing to uninstall first.

Manual de-installation notes are displayed when the installer script is first loaded

  • If the taskbar icon failed to remove, re-install and remove it first, before re-running the un-installer

Other Software​

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

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

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

mkisofs​

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.

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

Distro specifics​

Solus​

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

OpenSuse​

Support for SDL with OpenSUSE is patchy at best:

Windows and Mac HOSTS​

  • 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.

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.