qemus/qemu is a Docker container that wraps QEMU to run Linux virtual machines with KVM acceleration and a browser-based console. It is a practical tool for quick VM provisioning, but it carries specific host requirements and limitations that engineers should check before adopting it.

Can I use qemus/qemu commercially?

Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.

Is qemus/qemu still maintained?

Yes. The repository last received commits 8 days ago.

What programming language is qemus/qemu written in?

Mainly Shell, according to GitHub's language statistics.

qemus/qemu Review: Run QEMU VMs in Docker with Web Viewer

At a glance

What is it?: qemus/qemu is a Docker container that wraps QEMU to run Linux virtual machines with KVM acceleration and a browser-based console. It is a practical tool for quick VM provisioning, but it carries specific host requirements and limitations that engineers should check before adopting it.
Who is it for?: Adopt qemus/qemu if you need a fast, scriptable way to spin up Linux VMs on a Linux host with KVM and want a web-based console without building a QEMU command line by hand. Do not use it for Windows guests, ARM64 images, or any host without KVM access, such as Docker Desktop on macOS or Windows 10.
Can I use it commercially?: Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?: Yes. The repository last received commits 8 days ago.
What is it written in?: Mainly Shell, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.

DEEP OPEN-SOURCE ANALYSIS

Hysen Labs Editorial · August 8, 2026 · qemus/qemu

What This Container Solves and Who Should Care

qemus/qemu addresses a specific pain: running a full virtual machine without leaving the Docker ecosystem. Instead of installing virt-manager or learning a long qemu-system-x86_64 command, you set an environment variable and start a container. The README positions it for practical engineering and operations, which in practice means developers who need a disposable Linux VM for testing, CI runners that need isolated environments, or homelab users who want a quick web-accessible desktop. The web viewer on port 8006 removes the need for a separate VNC or SPICE client. The target audience is not cloud infrastructure teams managing thousands of nodes; it is individuals and small teams who want a VM as easily as they pull a Docker image.

The Mechanism: QEMU Inside a Container, Not a New Hypervisor

The project does not reimplement virtualization. It packages QEMU inside a Docker image and exposes configuration through environment variables. The container passes through /dev/kvm to the host kernel, which is what makes near-native performance possible. Without that device, the VM falls back to software emulation, which is slow. The README states that KVM acceleration is supported, and the compose example includes devices: - /dev/kvm. The container also uses /dev/net/tun and NET_ADMIN capability to set up networking. The BOOT variable controls what image gets downloaded, and the container automatically fetches the ISO or disk image from a list of known distributions. The storage volume at /storage holds the VM disk, which is created as a 64 GB file by default. The web viewer is served on port 8006, and the container handles the translation between the browser and the QEMU display.

Getting It Running: Commands and Configuration Keys

The simplest start is a single docker run command: docker run -it --rm --name qemu -e "BOOT=mint" -p 8006:8006 --device=/dev/kvm --device=/dev/net/tun --cap-add NET_ADMIN -v "${PWD:-.}/qemu:/storage" --stop-timeout 120 docker.io/qemux/qemu. For compose, the README gives a service block with BOOT: "mint", the same device and cap_add entries, and a volume mapping ./qemu:/storage. The BOOT variable accepts either a short name like debian or ubuntu, or a direct URL to an image file. Supported formats include .iso, .qcow2, .vmdk, .vhd, and .vhdx, and compressed archives like .gz or .xz are extracted automatically. You can also bind a local file to /boot.iso, /boot.img, or /boot.qcow2, which overrides BOOT. CPU and RAM are set with CPU_CORES and RAM_SIZE, for example RAM_SIZE: "8G" and CPU_CORES: "4". Disk size is set with DISK_SIZE, such as "128G", and the README notes this can resize an existing disk, though you must extend the partition manually inside the guest.

The Web Viewer and File Sharing: What Works and What Does Not

The web viewer is the primary interface. You connect to port 8006 in a browser and complete the OS installation there. Audio is disabled by default, and you enable it with AUDIO: "Y" plus a checkbox in the viewer's settings. The README says the audio stream is only active while that option is enabled, which is a thoughtful bandwidth saving. File sharing relies on 9pfs, a QEMU virtio feature. The host directory is mounted into the container at /shared, and the guest must have 9pfs support compiled into its kernel. The README gives the guest command: mount -t 9p -o trans=virtio shared /mnt/example. This is a real constraint. Many default Linux kernels do not include the 9p module, especially minimal server installs. If your guest lacks it, the mount fails and you have no fallback. USB passthrough and DRM native contexts are listed as features, but the README does not explain how to configure them, so expect to dig into the project's issues or source code.

Hard Requirements and a Clear Limitation: KVM Is Non-Negotiable

The most important limitation is the host requirement. The README states that Docker or Podman on a Linux host with KVM support is required. For Windows 11, you need Docker Desktop or Podman with nested virtualization enabled. Crucially, Docker Desktop on Linux, macOS, and Windows 10 does not provide KVM access to containers and is therefore not supported. That is a hard no for a large share of developers who use macOS as their daily driver. On a Mac, this container will not run with acceleration, and the README does not offer a workaround. Another limitation is that the BOOT list only covers Linux distributions. There is no Windows option; the README explicitly redirects Windows users to a separate project, dockur/windows. ARM64 images are also out of scope for this container; you need the companion qemu-arm image. So if your workload is Windows or ARM, this is the wrong tool.

A Real Alternative: Running QEMU Directly or Using dockur/windows

The most direct alternative is to run QEMU yourself, outside Docker. You would install qemu-system-x86_64 on the host, create a disk image with qemu-img, and launch with a command that includes -enable-kvm, -netdev user, and -vnc :0. This gives you full control over every QEMU option, including TPM, UEFI firmware, or custom network topologies. The trade-off is complexity: you must manage the command line, the display, and the networking manually. qemus/qemu abstracts all of that away, but you lose the ability to pass arbitrary QEMU flags unless the project exposes them. For Windows guests, the README points to dockur/windows, which is a separate container that bundles the necessary virtio drivers for Windows installation. That project is not a fork of this one, but it shares the same architecture pattern: a container wrapping QEMU with a web viewer. If your only need is a Linux VM, qemus/qemu is simpler; if you need Windows, switch to dockur/windows.

Maintenance, Upgrades, and License Implications

The repository shows an active release cadence: v7.47, v7.48, and v7.49 were pushed within eight days of each other in August 2026. That suggests frequent updates, likely tracking QEMU upstream releases. The license is MIT, which is permissive for commercial use, but it does not come with any warranty or support obligation. You are responsible for keeping the container updated, and given the rapid release cycle, you will want a strategy for pulling new tags. The README does not mention a specific upgrade path, so you would typically stop the container, pull the new image, and restart with the same volumes. The storage volume persists, so your VM disk survives updates. There is no mention of migration tools or snapshot management inside the container, so you should handle backups of the /storage directory yourself. The MIT license also means you can fork and modify the project, but the README's heavy use of shell scripts means you should review the entrypoint code before trusting it in a production environment.

Editorial conclusion

Adopt qemus/qemu if you need a fast, scriptable way to spin up Linux VMs on a Linux host with KVM and want a web-based console without building a QEMU command line by hand. Do not use it for Windows guests, ARM64 images, or any host without KVM access, such as Docker Desktop on macOS or Windows 10. Before deploying, verify that /dev/kvm is available to your container runtime, confirm that your kernel supports 9pfs if you plan file sharing, and test that the web viewer works on your network. This project is a wrapper, not a hypervisor, so its value depends entirely on the quality of the QEMU and KVM stack underneath it.

Official sources

Community notes