skip to content

Why does the Android Emulator crawl or refuse to start on some machines, and which VM acceleration does it need on each OS?

level: middleimportance: nice to knowfreq 22%

answer

  1. a hypervisor underneath
  2. the image must match the host CPU
  3. one hypervisor per host OS
  4. no VM inside a VM
  5. the accel flag and its check

basics

~20 s

The Android Emulator needs a hypervisor and a system image matching the host CPU: KVM on Linux, Hypervisor.Framework on macOS, Windows Hypervisor Platform on Windows. Without them it crawls or will not start; emulator -accel-check shows which.

solid answer

~40 s

The Android Emulator is a QEMU-based virtual machine. It is fast only when a **hypervisor** can run the guest's code directly on the host CPU. That needs three things: CPU virtualization extensions (VT-x or AMD-V, enabled in the BIOS, or Apple silicon), the platform's hypervisor (**KVM** on Linux, **Hypervisor.Framework** on macOS, **Windows Hypervisor Platform** on Windows), and a system image built for the host's architecture, x86_64 on Intel or AMD and arm64-v8a on ARM. It cannot be VM-accelerated inside another virtual machine. `emulator -accel-check` reports whether a usable hypervisor exists. `-accel on` refuses to start without one, and `-accel off` is unsupported software emulation that only runs when `ANDROID_I_WANT_MY_TCG=yes` is set.

code

console · 6 lines
console
$ ~/Android/Sdk/emulator/emulator -accel-check
accel:
0
KVM (version 12) is installed and usable.
accel
$ ~/Android/Sdk/emulator/emulator -avd ci_api37 -accel on -gpu software -no-window

go deeper

for a junior

Recall that the emulator needs a hypervisor and a matching system image, and name KVM, Hypervisor.Framework and Windows Hypervisor Platform.

for a middle

Explain why a mismatched ABI or a nested VM rules out acceleration, what -accel-check reports, and how VM and graphics acceleration differ.

for a senior

Show how you harden a runner: -accel on to fail fast, the right image ABI, deprecated flags removed, and a GPU mode that keeps snapshots usable.

for a principal

Weigh hosting emulators on runners you control, which need bare-metal or KVM-capable hosts, against the cost and flakiness of slow emulation.

## Two kinds of acceleration The Android Emulator runs Android inside a virtual machine built on the **QEMU** hypervisor. It can use the host's hardware in two separate ways, and people often confuse them: - **VM acceleration** runs the guest CPU's instructions directly on the host processor through a hypervisor. Without it, the emulator has to translate machine code block by block, which is very slow. - **Graphics acceleration** renders OpenGL ES and Vulkan on the host GPU. The `-gpu` flag controls it. A slow emulator usually means VM acceleration is missing. A crash or garbled screen usually points at graphics. ## What VM acceleration requires 1. **CPU virtualization extensions**: Intel VT-x, AMD-V (SVM) or Apple silicon. Intel and AMD processors also need second-level address translation (EPT or RVI). On PCs the extensions are often switched off in the BIOS by default. 2. **A matching system image**: x86 or x86_64 images on Intel and AMD hosts, arm64-v8a images on ARM64 hosts. An ARM image on an x86_64 host cannot use VM acceleration. 3. **A hypervisor for the host OS**, which you must run directly on the host. A VM-accelerated emulator cannot run inside another virtual machine. | Host OS | Hypervisor | Notes | |---|---|---| | Linux | KVM | the user needs permission to use KVM. `kvm-ok` from the `cpu-checker` package confirms `/dev/kvm` | | macOS | Hypervisor.Framework | built in. The old HAXM driver has not been an option since macOS 11 | | Windows | Windows Hypervisor Platform (WHPX) | recommended. The Android Emulator hypervisor driver is sunset on December 31, 2026 | Intel HAXM has been deprecated since January 2023, and from emulator 36.2 the emulator no longer uses it at all. ## Checking and forcing it `emulator -accel-check` prints whether KVM, WHPX or Hypervisor.Framework is installed and usable. On Linux, `egrep -c '(vmx|svm)' /proc/cpuinfo` printing 0 means the CPU has no hardware virtualization. The `-accel` startup flag takes three modes: - `auto` is the default. It works out whether acceleration is supported and uses it when it can. - `on` forces acceleration. If the hypervisor is missing or unusable, the emulator prints an error and does not start. On a CI runner this is the honest choice, because a broken host fails at once instead of producing a slow, flaky job. - `off` is software emulation. It is unsupported and very slow, and the emulator refuses it unless `ANDROID_I_WANT_MY_TCG` is set to `yes`. Older scripts still pass `-enable-kvm` or `-no-accel`. Both are on the deprecated list, where, depending on the emulator version, they are either ignored with a warning or rejected as unknown. Use `-accel` instead. ## Diagnosing a host that will not accelerate Work through the requirements in order, because each check rules out one cause: 1. Run `emulator -accel-check`. If it names a usable hypervisor, look at the image and the graphics mode next. If it does not, the host is the problem. 2. On Linux, check the CPU flags and run `kvm-ok`, then make sure the CI user is allowed to use KVM. 3. On Windows, turn on the **Windows Hypervisor Platform** feature and reboot. The older hypervisor driver cannot run alongside features that use the Windows Hyper-V hypervisor, which is one more reason to move to WHPX before the driver's end of life. 4. Confirm the AVD's image ABI matches the host CPU. 5. Confirm the job is not itself running inside a virtual machine. Other software that uses virtualization, such as some antivirus or anti-cheat tools, can also conflict, mostly on Windows. ## Graphics modes `-gpu auto` lets the emulator choose and is the recommended mode. `host` uses the host GPU. `software` picks the most suitable software renderer, and `lavapipe`, `swiftshader` and `swangle` name specific ones. Copied command lines often carry `swiftshader_indirect`, which was deprecated in emulator 36.4.9 along with `guest` and `swangle_indirect`. On a machine without a usable GPU, software rendering works, but the snapshot documentation warns that snapshots are not reliable with it. That matters if a CI job depends on Quick Boot. ## Common mistakes - Running the emulator inside a virtual machine and treating the slowness as a tuning problem. - Downloading an arm64-v8a image for an x86_64 Linux runner, or the reverse on Apple silicon. - Leaving `-accel auto` on CI so that a host without a hypervisor fails late and slowly instead of at once. - Copying `-enable-kvm` from an old script and assuming it still does anything.

  • On a CI runner, why choose `-accel on` over the default `auto`?
    `on` makes the emulator print an error and exit when the hypervisor is missing or unusable. A misconfigured runner then fails in seconds with a clear message, instead of running a job that times out or flakes. `auto` uses acceleration when it can, which hides the difference between a healthy host and a broken one.
  • Which `-gpu` mode suits a headless machine without a usable GPU, and what does it cost?
    `-gpu software` lets the emulator pick a suitable software renderer, and `swiftshader` or `lavapipe` name one explicitly. `swiftshader_indirect` from older scripts was deprecated in emulator 36.4.9. The cost is speed, and the snapshot documentation warns that snapshots are not reliable with software rendering.

  • The emulator accelerates fine inside any VM if it has enough RAM
  • -enable-kvm is how you switch on KVM acceleration today
  • An arm64-v8a image runs VM-accelerated on an x86_64 host
  • HAXM is still the recommended accelerator on Windows
  • Graphics acceleration and VM acceleration are one setting