qemus/qemu pins eight separate components and installs the emulator from a dated snapshot

The image assembles eight separately versioned pieces

The build file is where this project stops being a packaging exercise and becomes an assembly job.

There are eleven version arguments, and the interesting ones are not the emulator. There is the emulator itself at a Debian package version, firmware at a dated build, a BIOS implementation at a specific release, a machine protocol layer, a web service component, a utility toolkit, a remote-display layer, a rendering helper, and a network backend pinned by date.

Those are separate projects from the same organisation, and each ships its own version scheme. So this image is not QEMU packaged; it is a set of cooperating components assembled at chosen versions, and bumping any one of them is a deliberate decision rather than a dependency resolution.

One detail shows how much of the surface is per-architecture: the render component is fetched as a package from its own release page, only for one architecture, with a short download timeout. The rest come from the distribution.

The QEMU version is selected from a specific distribution snapshot; its age relative to another distribution depends on the versions being compared.

The whole userspace comes from an immutable snapshot

The single best engineering decision in this build file is one line long.

The emulator and its firmware are installed from a pinned snapshot archive rather than from a rolling release channel, and the snapshot identifier is a full timestamp passed in as a build argument. The corresponding sources entry carries a flag disabling validity-window checking, which is what makes an archived snapshot installable at all.

This is why the project can install a development release and still be reproducible. A rolling channel would give a newer emulator this week and a different one next month, and a pinned snapshot gives the same bits every time.

The trade is the usual one. Tracking the development release means the emulator here is newer than anything in a stable distribution, which is exactly why you would want this project, and it means you accept that this is not a stable channel.

There is also a second repository added, the non-free component archive, which is needed for the rendering package that was fetched separately. Two channels, both pinned or archived, and a build argument that names the exact moment the snapshot was taken.

Host support is narrower than four usage paths suggest

The requirements section is two lines and the second one is a correction.

Supported: a container runtime on a Linux host with hardware acceleration, or a container runtime on Windows 11 with nested virtualization enabled. Not supported: the desktop application on Linux, macOS, and Windows 10, because it does not pass hardware acceleration through to containers.

That last sentence rules out the path most people try first. Someone on a Mac with the desktop application installed will find the container starts and then behaves as though it has no acceleration, which is not a clear failure message.

Now set that against the usage section, which offers four routes: a compose file, a command line invocation, a Kubernetes manifest, and a one-click development environment button.

Those are not inconsistent. A development environment also needs to expose a working KVM device and support nested virtualization; being a virtual machine alone does not establish that it meets the requirement. But the juxtaposition is misleading if you read the usage section first, which is exactly the order a new user will read it in.

The container also needs two device nodes passed through and one network capability added, which the compose file shows explicitly.

services:
  qemu:
    image: qemux/qemu
    container_name: qemu
    environment:
      BOOT: "mint"
    devices:
      - /dev/kvm
      - /dev/net/tun
    cap_add:
      - NET_ADMIN
    ports:
      - 8006:8006
    volumes:
      - ./qemu:/storage
    restart: always
    stop_grace_period: 2m

The default disk grows, and the guest is not told

There is a sizing question with a trap in it, and the page answers it honestly.

The default disk is 64 gigabytes. You change it with a setting in the compose file, and the page goes further: the same setting can expand an existing disk without data loss.

Then the caveat. The added capacity appears inside the guest as unallocated space, so the partition has to be extended manually from inside the guest operating system before the new space is usable.

That is the standard behaviour of every virtual disk tool and it is the single most common support question in this category, so documenting it in a tip is genuinely useful. The alternative, resizing silently and leaving a guest with a filesystem it cannot see, is what turns a two-line question into a forum thread.

Memory and processor sizing work the same way but without the caveat: two cores and two gigabytes by default, changed with two separate settings. No post-resize step is needed there, which makes the asymmetry worth noticing.

Windows and ARM guests are delegated elsewhere

Two of the platform questions are answered by pointing at other projects, and that is more informative than a paragraph of caveats would be.

For a 64-bit ARM guest image, the answer is a sibling container from the same organisation, named separately. For Windows, the answer is a community project, and the reason given is that it bundles the drivers required during installation.

So the project's own scope is deliberately narrow: Linux guests, with everything else pointed at a more appropriate container. That is a healthier answer than attempting Windows and failing, and it is worth knowing before you plan a Windows virtual machine on this.

The guest distribution list reinforces the point. It is 23 Linux distributions, from a 60 megabyte minimal build to a 7 gigabyte full desktop, plus one non-Linux entry. Sizes are listed per distribution, which is a thoughtful touch when the image is downloaded automatically on first boot.

You can also supply your own image, either as a download address or as a file mounted into the container, and the page documents eight image formats plus automatic extraction of compressed ones.

Host file sharing depends on the guest kernel, not the container

Shared folders are the feature most likely to fail on first attempt, and the reason is a dependency on the other side.

To share a host directory, the guest operating system must have the 9p filesystem support compiled in or available as a module. If it does not, nothing in the container configuration can make it work.

Once the guest supports it, you add a bind mount and then run a mount command inside the guest using the virtio transport. The host directory appears in the guest at the path you choose.

So the setup order matters: check the guest kernel first, then write the container configuration. Getting that backwards produces a mount error inside a guest that looks like a container misconfiguration.

This is also why the project advertises passthrough and host sharing together in the feature list without qualification, which slightly undersells how much of the work is on the guest side.

Audio streams only while you are listening

Audio is off by default, which is the right default for a container, and the way it is enabled has one good detail.

Two changes are needed. An environment variable turns the feature on, and then the audio option has to be enabled under advanced settings in the web viewer. It is deliberately a two-step setup rather than a single switch.

The detail is what the page says about cost: the stream is only active while the option is enabled, so it uses no extra bandwidth otherwise.

That matters more than it sounds. A remote viewer session over a network is exactly the situation where an always-on audio stream would be a complaint, and making the stream conditional on an explicit toggle means the default cost is zero and the decision to pay is visible in the interface.

The rest of the configuration surface is small and uniform: a variable for the boot image, one for disk size, two for processor and memory, one for audio, and the bind mounts for storage and shared folders. Every one of them is documented with the value it defaults to.

Editorial conclusion

Use this if you want a throwaway or persistent Linux guest you can reach through a browser tab, particularly on a homelab or a cluster where you would rather not manage hypervisor packages. Two things to check first. Host support is narrower than the usage section implies: it supports a Linux host with KVM or Windows 11 with nested virtualization enabled, and explicitly rules out Docker Desktop on macOS. And the QEMU package is pinned to a distribution snapshot, while guest images can also be selected from the documented list, supplied via URL, or mounted locally. Pin and verify the guest image separately if reproducibility matters.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes