A rootless Android app that boots Alpine Linux: run containers (Podman/Docker/LXC) and GUI desktop apps.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Backends: QEMU & AVF · Podroid docs</title>
<meta name="description" content="How to choose between QEMU (TCG) and AVF (pKVM), how to grant AVF permissions, and what differs between the two backends." />
<link rel="icon" type="image/png" href="../logo.png" />
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link href="https://fonts.googleapis.com/css2?family=DM+Sans:ital,opsz,wght@0,9..40,300;0,9..40,400;0,9..40,500;0,9..40,600;1,9..40,400&family=DM+Mono:wght@400;500&display=swap" rel="stylesheet" />
<link rel="stylesheet" href="style.css" />
</head>
<body>
<nav>
<a class="nav-logo" href="../index.html"><img src="../logo.png" alt="Podroid" />Podroid</a>
<button class="menu-toggle" aria-label="Toggle menu">☰</button>
<ul class="nav-links">
<li><a href="../index.html">Home</a></li>
<li><a href="index.html" class="cta">Docs</a></li>
<li><a href="https://github.com/ExTV/Podroid">GitHub</a></li>
</ul>
</nav>
<div class="layout">
<aside class="sidebar">
<h4>Getting started</h4>
<ul>
<li><a href="index.html">Overview</a></li>
<li><a href="getting-started.html">Getting started</a></li>
<li><a href="how-it-works.html">How it works</a></li>
</ul>
<h4>Going deeper</h4>
<ul>
<li><a href="performance.html">Performance & why it's slow</a></li>
<li><a href="backends.html" class="active">Backends: QEMU & AVF</a></li>
<li><a href="networking.html">Networking & ports</a></li>
<li><a href="packages.html">Packages & services</a></li>
<li><a href="migrations.html">Updates & migrations</a></li>
<li><a href="desktop.html">Desktops & X11 viewer</a></li>
<li><a href="settings.html">Terminal & settings</a></li>
</ul>
<h4>Reference</h4>
<ul>
<li><a href="limitations.html">Limitations & troubleshooting</a></li>
<li><a href="use-cases.html">Use cases</a></li>
</ul>
</aside>
<main class="content">
<h1>Backends: QEMU & AVF</h1>
<p class="lead">Podroid has two VM engines behind one setting. The default uses QEMU with software CPU emulation and works on any device. On Pixel 8/9/10 and similar devices that ship pKVM, the AVF backend runs the guest on real CPU cores for near-native speed.</p>
<h2>Choosing a backend</h2>
<p>Go to <strong>Settings → Advanced → Backend</strong>. The three options are:</p>
<ul>
<li><strong>Auto</strong> (default) - Podroid probes the device at startup and uses AVF if the feature, both permissions, and non-protected VM support are all present; otherwise it falls back to QEMU. This is the right choice for most users.</li>
<li><strong>AVF (KVM)</strong> - always use AVF. On a device that cannot run it, the VM runs on QEMU instead, and the app states why: a notice on Home, a suffix on the Status screen, and a caption under the AVF chip in Settings.</li>
<li><strong>QEMU (TCG)</strong> - always use software emulation, even on a device that supports AVF.</li>
</ul>
<div class="callout note">
<span class="label">Stop the VM first</span>
<p>Changing the backend setting takes effect at the next VM start. The VM must be stopped before you switch.</p>
</div>
<h2>QEMU (TCG)</h2>
<p>The QEMU backend is the default and works on <strong>any ARM64 Android 8+ device</strong> with no setup beyond installing the app. The guest CPU is emulated in software via TCG (Tiny Code Generator). See <a href="performance.html">Performance & why it's slow</a> for a full explanation of where the overhead comes from and what Podroid does to reduce it. The short version: simple workloads are 2-5x slower than native; JIT-heavy workloads (Node, JVM, compilers) are slower still because of double-JIT and cold-cache process-spawn costs.</p>
<p>QEMU supports both <strong>TCP and UDP port forwarding</strong>. Rules you configure in the Port Forwarding screen work for both protocols.</p>
<h2>AVF (pKVM)</h2>
<p>The Android Virtualization Framework (AVF) is a system hypervisor shipped on some Android devices. On devices that include pKVM (protected Kernel-based Virtual Machine), Podroid can run the guest directly on physical CPU cores - no TCG translation, no double-JIT, no cold-cache overhead. CPU-bound tasks that crawl on QEMU run at near-native speed on AVF.</p>
<p>AVF is currently available on <strong>Pixel 8, Pixel 8a, Pixel 9, Pixel 9 Pro, Pixel 9 Pro XL, and Pixel 10</strong> series devices (and any other Android device your manufacturer ships with pKVM). Two development-mode permissions must be granted once before Podroid can open a VM.</p>
<h3>Setting up AVF</h3>
<p><strong>Step 1 - Confirm the device supports AVF.</strong> Run the following in a terminal with ADB access to the device:</p>
<pre><code><span class="p">$</span> adb shell pm list features | grep virtualization_framework</code></pre>
<p>If the command prints a line containing <code>android.software.virtualization_framework</code>, the device supports AVF. If the command prints nothing, the device does not have pKVM and AVF is not available.</p>
<p><strong>Step 2 - Grant the two permissions.</strong> These are development-mode permissions not exposed in the system UI. Grant them over ADB:</p>
<pre><code><span class="p">$</span> adb shell pm grant com.excp.podroid android.permission.MANAGE_VIRTUAL_MACHINE
<span class="p">$</span> adb shell pm grant com.excp.podroid android.permission.USE_CUSTOM_VIRTUAL_MACHINE</code></pre>
<div class="callout note">
<span class="label">No PC? Use Shizuku.</span>
<p>If you do not have a computer handy, install <a href="https://shizuku.rikka.app/">Shizuku</a> and start it (over ADB or wireless debugging). Then open Shizuku's <code>rish</code> shell and run the same two <code>pm grant</code> lines above, replacing <code>adb shell</code> with just the <code>pm grant ...</code> command directly inside <code>rish</code>.</p>
</div>
<p><strong>Step 3 - Run the AVF diagnostic.</strong> In Podroid, go to <strong>Settings → About → "AVF (pKVM) diagnostic"</strong>. This runs a probe and a smoke test that checks: the virtualization_framework feature flag, both permissions, the presence of <code>/apex/com.android.virt</code>, the AVF system service, and the hypervisor capabilities reported by the kernel. If it reports success on all points, you are ready. Set <strong>Backend</strong> to <strong>Auto</strong> (or <strong>AVF</strong> if you want to force it) and start the VM.</p>
<h3>Permission lifetime</h3>
<p>The two <code>pm grant</code> permissions <strong>persist across reboots and in-place app updates</strong>. You do not need to re-grant them after an OTA or a Podroid update installed over the existing app. However, they are <strong>lost on uninstall</strong>: if you uninstall and reinstall Podroid, run the two <code>pm grant</code> commands again before using AVF.</p>
<h2>How Auto-selection works</h2>
<p>When the backend is set to Auto, Podroid checks four conditions at startup: (1) the <code>android.software.virtualization_framework</code> feature is present, (2) <code>MANAGE_VIRTUAL_MACHINE</code> is granted, (3) <code>USE_CUSTOM_VIRTUAL_MACHINE</code> is granted, and (4) the device advertises support for <strong>non-protected VMs</strong>. All four must pass. If any fails, Podroid falls back to QEMU and the VM starts with software emulation - announced in the same places as a forced-AVF fallback: a Home notice, a Status suffix, and a caption under the AVF chip in Settings.</p>
<p>Condition (4) is the non-obvious one. pKVM can operate in two modes: <em>protected</em> (guest memory is encrypted and the host cannot inspect it) and <em>non-protected</em>. Podroid's guest image is a standard Alpine Linux squashfs - it does not meet the signing and measurement requirements for protected VMs. A device that only advertises protected VM support cannot run Podroid's image under AVF, so Auto falls back to QEMU on such devices.</p>
<div class="callout note">
<span class="label">Protected-only device and want hardware speed? You'll need root.</span>
<p>If your device only supports protected VMs, AVF cannot run Podroid's custom kernel and there is no app-side workaround: the protected-VM firmware (pvmfw) only boots payloads that carry a signed, verified boot image, which a general-purpose Linux kernel does not. The only remaining route to hardware virtualization is to open the hypervisor device node (<code>/dev/kvm</code>, or <code>/dev/gunyah</code> on Qualcomm SoCs) directly, which requires <strong>root</strong>. Podroid is deliberately no-root, so it uses QEMU on these devices. If you are rooted and on a recent Qualcomm Snapdragon device (8 Gen 3 / SM8650 or newer with Gunyah enabled), a separate, unaffiliated project, <a href="https://github.com/Droid-VM/DroidVM" target="_blank" rel="noopener">DroidVM</a>, runs VMs through the Gunyah hypervisor or KVM for near-native speed.</p>
</div>
<h2>Differences between backends</h2>
<table>
<thead>
<tr>
<th>Feature</th>
<th>QEMU (TCG)</th>
<th>AVF (pKVM)</th>
</tr>
</thead>
<tbody>
<tr>
<td>Device requirement</td>
<td>Any ARM64 Android 8+</td>
<td>Device must ship pKVM (recent Pixels and select others)</td>
</tr>
<tr>
<td>Setup required</td>
<td>None</td>
<td>Two <code>pm grant</code> commands (once)</td>
</tr>
<tr>
<td>CPU speed</td>
<td>Software emulation (2-5x+ overhead)</td>
<td>Near-native (hardware VMs, no TCG)</td>
</tr>
<tr>
<td>Port forwarding protocols</td>
<td>TCP and UDP</td>
<td>TCP and UDP</td>
</tr>
<tr>
<td>vCPU count</td>
<td>Configurable (1 to device core count)</td>
<td>1 vCPU = one core; >1 = all host cores, with automatic fallback to fewer if a device can't boot them all</td>
</tr>
<tr>
<td>Terminal console</td>
<td>hvc0 via QEMU virtio-console</td>
<td>hvc0 (same guest view, different host path)</td>
</tr>
<tr>
<td>Downloads folder sharing</td>
<td>Supported (virtio-9p)</td>
<td>Supported (in-process 9p2000.L server over vsock)</td>
</tr>
<tr>
<td>USB device passthrough</td>
<td>Supported (opt-in; adds a USB controller at boot)</td>
<td>Not available - there is no QMP channel to stream device handles to the VM</td>
</tr>
<tr>
<td>Verbose logging toggle</td>
<td>Not applicable</td>
<td>"Verbose AVF logging" in Settings → Advanced (useful for bug reports)</td>
</tr>
</tbody>
</table>
<div class="callout note">
<span class="label">Multi-core AVF and automatic fallback</span>
<p>On some units (notably Tensor G3/G4 Pixels - 8 / 8a / 8 Pro and the 9 series) the all-cores topology trips secondary-CPU bringup early in boot, before any console output appears. As of v1.2.5 this is handled automatically: AVF starts with the cores you chose, and if the VM resets during boot Podroid retries with fewer cores and remembers the highest count that boots on your device - no action needed. The manual <strong>Use 1 core</strong> and <strong>Switch to QEMU</strong> options remain as fallbacks, and QEMU (TCG) is reliable on all devices. See <a href="limitations.html">Limitations & troubleshooting</a>.</p>
</div>
<div class="pagenav">
<a class="prev" href="performance.html"><span class="dir">Previous</span>← Performance</a>
<a class="next" href="networking.html"><span class="dir">Next</span>Networking & ports →</a>
</div>
<p class="docfoot">Podroid is free software (GPL). Docs for v1.3.0. Found something inaccurate? <a href="https://github.com/ExTV/Podroid/issues">Open an issue</a>.</p>
</main>
</div>
<script>
document.querySelector('.menu-toggle').addEventListener('click', function () {
document.querySelector('.sidebar').classList.toggle('open');
});
</script>
</body>
</html>