# QEMU: A Machine Emulator and Virtualizer for Cross-Architecture Work

> QEMU emulates complete machines in software and can hand CPU execution to KVM or Xen when the host and guest architectures match. Here is how it is built, run, and where it stops being the right tool.

**qemu/qemu** — Official QEMU mirror. Please see https://www.qemu.org/contribute/ for how to submit changes to QEMU. Pull Requests are disabled. Please only use release tarballs from the QEMU website.

- Repository: https://github.com/qemu/qemu
- Website: http://www.qemu.org
- Stars: 13,761 · Forks: 7,213
- Language: C
- License: NOASSERTION
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/qemu-qemu

## What QEMU solves, and who ends up using it

QEMU is a generic and open source machine and userspace emulator and virtualizer. The problem it addresses is architectural mismatch. Code built for one machine cannot normally run on another, and QEMU removes that constraint in two distinct ways. As a machine emulator it implements a complete computer in software, with no hardware virtualization support required, so an operating system written for an ARMv7 board can run on an x86_64 PC. As a userspace emulator it implements Linux and BSD kernel interfaces, letting a binary compiled against one architecture ABI, such as Linux PPC64, run on a host using a different ABI, such as Linux x86_64. That second mode involves no hardware emulation at all, only CPU and syscall emulation.

The second audience is people who never invoke QEMU directly. The README states that QEMU aims to fit a variety of use cases, from direct invocation by users who want full control over its behaviour and settings, to integration into higher level management layers through a stable command line interface and monitor API. It is commonly invoked indirectly via libvirt when using open source applications such as oVirt, OpenStack and virt-manager. If you have used any of those, you have used QEMU without necessarily knowing it.

The third audience is developers working on QEMU itself. The repository is the upstream source, and the README spends as much space on patch submission as on building. That is a signal about what this repository is: the canonical tree, not a distribution channel. The README is explicit that pull requests are disabled on the mirror and that release tarballs should come from the QEMU website.

## Dynamic translation, hypervisor handoff and the two emulation layers

The mechanism has two halves, and confusing them is the most common source of wrong expectations.

When QEMU emulates CPUs directly, it uses dynamic translation and the README claims very good performance for that approach. Every guest instruction is translated, so the guest architecture does not need to match the host. This is what makes cross-architecture work possible at all.

When the guest architecture matches the host, QEMU can instead integrate with the Xen and KVM hypervisors, providing emulated hardware while the hypervisor manages the CPU. The README describes the result as near native CPU performance. The trade-off is immediate: you get speed, but you lose the cross-architecture capability, because KVM runs guest instructions on the host CPU.

The userspace mode is a third path. QEMU provides userspace API virtualization for Linux and BSD kernel interfaces, translating CPU instructions and system calls rather than emulating a whole board. It is the lightest of the three and the least useful if what you actually need is a bootable guest.

The build system reflects the breadth of this scope. The top level contains accel/, audio/, authz/, backends/, block/, chardev/, crypto/, disas/, docs/, dump/, ebpf/, fpu/, fsdev/ and more, alongside a Kconfig and Kconfig.host pair and a configure script. QEMU is multi-platform by intent, and the README says it is intended to be buildable on all modern Linux platforms, OS-X, Win32 via the Mingw64 toolchain, and a variety of other UNIX targets. That breadth is also why a full build is heavy: the tree carries many target architectures and device models in one source repository.

## Building QEMU from source and booting a first guest

The README gives the simple build steps directly. Create a build directory, change into it, run the configure script from the parent, then make.

```bash
mkdir build
cd build
../configure
make
```

This is an out-of-tree build. The Makefile enforces a related constraint: it errors out if the main directory path contains spaces or colons, and it refuses to configure a tree that has already been used for an in-tree build. If you see an error about the source tree already containing config-host.mak, that is the guard firing.

Host-specific instructions are not in the README itself. It points to the QEMU wiki pages for Linux, Mac and W32 hosts, which is where platform-specific dependency lists live.

Once built, the binary you get depends on the targets you configured. A typical invocation names a machine and a disk image. The README does not include a runnable example command, so the exact flags for your guest come from the online documentation under docs/ rather than from this repository's README.

If you only want to run QEMU rather than build it, note what the README says about distribution: release tarballs come from the QEMU website, and vendor binary packages are the normal route on most systems. The mirror README states plainly that pull requests are disabled, so this repository is a source of code and patches, not of packaged binaries.

For contributors, the workflow is email-based rather than pull-request-based. The README shows the clone command and describes the patch path.

```bash
git clone https://gitlab.com/qemu-project/qemu.git
```

Patches go to the qemu-devel@nongnu.org mailing list, formatted with git format-patch or git send-email, and every patch must carry a Signed-off-by line from the author. The README also mentions a git-publish utility for repeated patch series revisions, which tags a series as my-feature-v1 and later my-feature-v2.

## Where QEMU is the wrong tool

The most important limitation is the one already implied by the architecture: near native performance and cross-architecture emulation are mutually exclusive in this design. If your guest architecture does not match your host, you fall back to dynamic translation, and the README's claim of near native performance applies only to the hypervisor-backed path. Anyone planning a production workload on emulated hardware across architectures should read that sentence twice.

The second limitation is the interface. QEMU can be invoked directly by users who want full control, and the README frames that as a feature. In practice it means the direct path is a command line and a monitor API, not a desktop application. The README names virt-manager, oVirt and OpenStack as the indirect route via libvirt. If you want a graphical virtual machine manager, you are looking at the layer above QEMU, not at QEMU.

The third is build cost. QEMU is multi-platform software covering many targets, and the README's build section is three commands but the tree is far larger than that suggests. There are no release notes or version history in this README; it defers to the wiki ChangeLog and to git history. That means you will not learn from this file which release you are building or what changed.

Finally, there is a licensing boundary. QEMU as a whole is released under the GNU General Public License, version 2, and the repository carries both COPYING and COPYING.LIB files. The README says to consult the LICENSE file for full details. Whether that fits your distribution model is a question for your own counsel, not something this README answers.

## QEMU next to VirtualBox and next to KVM alone

The comparison people reach for first is VirtualBox, and the difference is structural rather than a matter of features. VirtualBox is a virtual machine product with its own management interface. QEMU is an emulator and virtualizer that exposes a command line and a monitor API and expects a management layer such as libvirt, virt-manager, oVirt or OpenStack to sit above it. QEMU's distinguishing capability is emulating a complete machine in software without hardware virtualization support, which is what makes running an ARMv7 guest on an x86_64 host possible. A virtualizer that depends on host virtualization extensions cannot do that.

The second comparison is QEMU against KVM, and it is a category error to treat them as rivals. They are layers. QEMU integrates with KVM to provide emulated hardware while KVM manages the CPU, which is how the near native path works. Choosing KVM alone means giving up QEMU's device models and its cross-architecture emulation. Choosing QEMU without KVM means accepting translation overhead in exchange for running guests your host CPU cannot execute natively. The README describes both arrangements in the same paragraph because they are options within one tool, not competing products.

A third point of difference worth noting is governance and contribution model. QEMU's changes flow through a mailing list with Signed-off-by requirements, and the mirror disables pull requests. Projects that accept pull requests on their mirror have a lower barrier for a casual fix. QEMU's process is deliberate and slower for drive-by contributions.

## Maintenance status, licensing and the cost of staying current

The repository is not archived, and the last push was on 2026-09-20. That is a single day before the date of this article, which tells you the tree is receiving commits continuously. It does not tell you anything about release cadence: the README contains no release notes and no version history, and it points to the wiki ChangeLog and to git history for version information. If you need to know what shipped in a given release, this file will not tell you.

The upgrade cost follows from the architecture of the project. QEMU's stated goal of a stable command line interface and monitor API is what makes it safe to build a management layer on top of it, and that stability is the reason libvirt and the applications above it can exist. The flip side is that the surface is large: the top level of the tree carries accel/, block/, chardev/, crypto/, disas/, docs/ and many more directories, and a build covers whichever targets you configured. Rebuilding after an upgrade is a real cost, and the README's build section does not discuss incremental builds or build caching.

There is also a Rust component in the tree. The Cargo.toml defines a workspace with members under rust/hw/char/pl011, rust/hw/timer/hpet and rust/tests, pins rust-version to 1.83.0, and sets the workspace license to GPL-2.0-or-later. The manifest notes that docs/devel/rust.rst must be updated when the minimum supported Rust version changes. This matters for anyone building from source on a system with an older toolchain: a Rust compiler is now part of the build requirements for those components.

On licensing, the README states that QEMU as a whole is released under the GNU General Public License, version 2, and directs readers to the LICENSE file for full details. The repository also contains COPYING and COPYING.LIB. The Cargo workspace declares GPL-2.0-or-later for the Rust members, which is not identical to the version 2 statement in the README. If you are embedding QEMU or linking against it, read both files rather than relying on the README summary. This is a description of what the files say, not legal advice.

## Conclusion

Adopt QEMU if you need to run operating systems or binaries for a different architecture than your host, or if you are building a management layer on top of its command line and monitor API. Do not adopt it if you want a desktop virtual machine manager with a graphical interface and no interest in the command line, or if you need hardware virtualization on a host whose architecture differs from the guest's. Before committing, verify three things: that your target architecture is among the emulated machines listed in the docs, that KVM is available on your host if you expect near native CPU performance, and that the GPL version 2 licensing of QEMU as a whole is compatible with how you intend to distribute your integration.

## FAQ

### Is QEMU free to use?

Yes. QEMU is described in the README as a generic and open source machine and userspace emulator and virtualizer, and it states that QEMU as a whole is released under the GNU General Public License, version 2, with full details in the LICENSE file.

### What processors can QEMU emulate?

The README does not list supported architectures. It gives the capability in general terms: QEMU can emulate CPUs directly, which lets it run operating systems made for one machine, such as an ARMv7 board, on a different machine, such as an x86_64 PC board. The list of emulated machines lives in the online documentation generated from the docs/ folder.

### Is QEMU safe to use?

The README does not make security claims and does not discuss isolation or sandboxing. What it does say is that QEMU can integrate with the Xen and KVM hypervisors, in which case the hypervisor manages the CPU while QEMU provides emulated hardware. Whether that arrangement meets your isolation requirements is not addressed in this file.

### Which is better, QEMU or VirtualBox?

The README does not compare QEMU to VirtualBox. It positions QEMU as something invoked either directly, with full control over behaviour and settings, or indirectly via libvirt when using applications such as oVirt, OpenStack and virt-manager. Its distinct capability is emulating a complete machine in software without hardware virtualization support, which is what allows cross-architecture guests.

## Sources

- [Issues](https://github.com/qemu/qemu/issues)
- [Project website](http://www.qemu.org)
- [qemu/qemu on GitHub](https://github.com/qemu/qemu)
- [README](https://github.com/qemu/qemu/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/qemu-qemu