Skip to main content

FAQs-and-Help

All qqX scripts are carefully Shellcheck linted and have full error handling routines.

qqX and Quickemu compatibilty​

qqX is fully compatible with any existing Quickemu machines and will run any Quickemu builds.

Installing qqX can easily solve problems with Quickemu and/or QuickGui not working.

Both Quickemu and QuickGui will be able to launch any qqX built machines.

For qqX features, like second drives and shared SDL accessible drives, the content can easily be transferred to the standard Quickemu Public drive, if needed.

My Virtual Machine won't work​

Download and try a different machine, a different distro .... Does that work?

Is it the specific distro that won't work? Or is it the whole of your Setup?

Have you tried switching to FreeSpirit or or even backwards to HomeBird?

Have both qqX and Quickemu stopped following a system update? It may be that a system update broke things.

Check for new commits to see if any fixes have been issued. Also check the qqX development branches.

When checking for issues make sure to view is:closed not just is:open

To get the very latest code, download from the 'clone' button, not from the releases tab.

Do the same for Quickemu

Try Quickemu directly at the command prompt from the .conf folder: quickemu --vm name.conf

Paste a copy of the quickemu script into that folder too. Run with a ./ prefix, eg. ./quickemu --vm name.conf

Make sure that both your system and all your underlying Quickemu dependencies are up-to-date.

Also check your Host OS repository for different Qemu and Quickemu variants eg. base, full and desktop etc

Be also aware that new-user/walled garden distros, plus those offering Long Term Support, may not always have the latest updates.

See https://github.com/quickemu-project/quickemu/issues/928

My downloads are very slow​

This could be your router/ISP. The download servers may be busy. Try again another time.

See https://github.com/quickemu-project/quickemu/issues/898

Newer versions of qqX allow you to stop the download and restart. Try this. It can usually reconnect you to another server or another mirror and often resolve things.

Windows download errors​

If you keep retrying, and from the same IP address, then Microsoft will block you ....

See https://github.com/quickemu-project/quickemu/issues/938

Windows Installation​

See the Windows guide for driver issues and general setup notes.

Problems can also occur from Apparmor

  • For swtpm: Could not open UnixIO socket: Permission denied, see the tpm notes

MacOS hangs when running the setup​

This was a common event. The setup often used to just sit there and appear to be doing nothing.

  • Improvements during 2024 changed things. Except for Sequioa 15.4 and above, setups should now work smoothly for all versions.

  • See the MacOS guide. Also see qqX issue #9

SDL vs Spicy​

Qemu runs the Virtual Machines via a 'local server' that it sets up on your computer.

We can use different methods to access and view the server output. SDL & Spicy are two of the methods that are supported by Qemu.

Both Quickgui and GnomeBoxes currently ONLY offer Spicy.

Qemu does offer a few other display modes, some of which are not fully documented. Most of these variants can be experimented with from the standard qqX interface or from the Quickemu command line.

qqX has an additional option of SDL file sharing and disk mounting.

At 2025 it should be noted that aside from RedHat patches being pushed to their Virtio ISO, Spice development seems to have ground to a halt. Whilst, on the other hand, SDL progress, spurred on by work by Valve on their gaming software Steam and Proton, is quite active.

  • SDL tends to be faster and crisper than Spicy but currently it will only scale at boot time or with GL turned off.

  • Spicy is less sharp but is fluid scaleable in GL mode and does offer cut and paste between the guest and host.

At 2025, cut and paste is available with SDL3 but we are still waiting for Qemu support on this.

  • It's a known issue with OpenSUSE that SDL is not available ... No workarounds appear present.

Windows will generally run faster with GL turned off. Set gl="off" in the .conf file.

  • See notes on GPU pass-thru, in the advanced section, if faster performance is needed.

GTK has generally less abilities but can sometimes work when the other two might fail.

Another mode is 'headless' for use with guest server setups. See further notes in the qqX settings file.

There is a general SDL discussion on the QuickEmu pages.

What are the Tiano Core Security Updates​

qqX refreshes the OVMF files in the VM folder from time to time to make sure that any Tiano updates get implemented.

This is especially important for MacOS folders as they also contain code files.

  • You can run the 'refresh_tiano_vars' process manually run via the [rtv] option in the utils menu.

I am running out of disk space​

Ideally the Virtual Machine should have been allocated a generous size from the outset. But things aren't always that way ...

See the qqX help section on easy disk resizing

I need to edit / repair the VM partitions​

qqX has a neat ISO boot option that works just like booting your desktop computer from a USB repair disk

See the help section on booting from iso's

I can't get the mouse to work​

Sometimes, especially with non-Linux distros, we need to tweak the .conf file. Quickemu defaults to mouse="tablet" if an option is not supplied. You can try mouse="usb" or ="virtio" for example. The qqX conf editor will show the full list.

If you still having problems, try custom tweaking the usb boot-setup. Switch xhci to ehci maybe?

See Custom-Qemu-boot-parameters for more details.

USB won't work​

Most of the the big money in Virtual Machine development tends to target server deployment. The running of virtual desktops is less of a commercial priority and desktops vary greatly too. Some of these areas can be problematic ...

In the conf file, try usb-controller= 'ehci' (default), 'xhci', 'none'

Audio won't work​

As with USB, this is not a priority area. Newer versions of Qemu are more supportive. See this quickemu commit.

In the conf file, try sound card= 'intel-hda' (default), 'ac97', 'es1370', 'sb16', 'usb-audio', 'none'

The quickemu PPA won't work​

PPA's are intended for Ubuntu host distros only.

With the development of qqX built-ins, the installation of Quickemu is no longer essential.

If you are using Ubuntu, make sure that the PPA didn't get disabled during a distro release update. See Software & Updates > Other software.