Home

qqX - Quickemu Virtual Machine Manager

qqX will generally run straight 'out of the box' on the vast majority of Linux distributions.

Host Systems

• Installation on Windows hosts has now been partly implemented via the WSL Linux Subsystem with support hopefully in an upcoming release.

• Running on physical MacOS hosts is unfortunately not supported at present, due to BSD variances.

• Users of non-standard OS's such as NixOS, should view the installer script, plus read issue #1 and details on Filesystem Hierarchy Standards here

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

Install from scratch

• Most users need only install qemu spice-gtk and qqX

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

• No further software, support structures or dependencies should be needed.

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 gtk may be listed as spice-client-gtk

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.

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

• This PPA may be used: https://launchpad.net/~stefanberger/+archive/ubuntu/swtpm-noble

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 notes here

Install on top of Quickemu

Test out the qqX difference on your existing VM's:

• qqX has been designed to work happily alongside quickgui or any quickemu shortcuts, if you already have them.

• The installation of quickemu is not essential but Ubuntu packages are available and will install the dependencies ...

The standard Quickemu instructions may be found on the quickemu-project pages

qqX

• Download via the latest qqX release which will have been carefully tested.

• Alternatively, if newer branches are present, they may have the latest tweaks or features, and may possibly have bug fixes. Switch branches, click on the 'code' button and 'download zip'.

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

File Manager

• For most usage cases, simply right clicking in a file manager and selecting extract or extract with ....

Cmd Line

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

When you are ready

Run 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'

  

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

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

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

Uninstall

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

Default VM folder

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

  

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

• An auto-detector will tell you when new qqX releases are available.

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

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.

Other Installation Tips

All folders can be easily moved around, but make sure that they have their .conf file next to them. And make sure the config internals point correctly. From version 1.7 onwards, there is now a handy move and rename tool to make this even easier still.

Multiple folders can help organise your distros. You can edit which VMs to show first in the general settings.

If you you are finding the interface a bit cramped, re-run the installer making sure to run the desktop part. This will allow you to tweak the terminal size.

The qqX downloader script will have done this. But you can manually check the download integrity by opening a terminal in the release's download folder and typing sha256sum -c qqX- "tab-key" .s "tab-key", if you have downloaded both of the named files from the release tab.

Finally

Please report any unnoticed errors. Also any difficulties you may have encountered. By using this software you become a valued member of the community and can help make this software better for others.