Limitations & troubleshooting
Podroid runs a real VM on hardware that was not designed for it. This page documents every known limitation honestly, and explains how to work around the most common problems.
Limitations
| Category | Limitation | Detail |
|---|---|---|
| CPU / acceleration | No KVM on the default QEMU path | KVM requires root access to /dev/kvm, which Podroid does not have. The default backend uses QEMU TCG (software CPU emulation), which is 5-20x slower than native for CPU-bound work. AVF/pKVM is the only hardware-accelerated option and is Pixel-only; see Backends. |
| Architecture | ARM64 only | The app ships an arm64-v8a ABI only. x86, x86_64, and 32-bit ARM devices are not supported. x86 container images pulled inside the VM will run under double emulation (guest ARM64 + QEMU TCG re-emulates x86), which is extremely slow. |
| OS version | Android 9+ required (minSdk 28) | Features such as memfd_create and the required SELinux/seccomp policy are only stable from API 28. Android 8 is blocked additionally by glib/iconv linking issues in the QEMU build. |
| AVF backend | Pixel pKVM devices only; two ADB permissions required | AVF uses the Android Virtualization Framework, which requires a device that ships pKVM (currently Pixel 8 and later). Two one-time adb grants (or Shizuku) are needed before AVF can start. Devices that only support protected VMs and not non-protected VMs cannot use the AVF backend at all; Podroid falls back to QEMU automatically. |
| AVF networking | TCP port forwarding only | The AVF backend forwards TCP ports via the in-app port-forward rules. UDP rules are silently ignored when AVF is active. If you need UDP (e.g. DNS on port 53 serving LAN clients), switch to QEMU. |
| AVF CPU count | No fine-grained vCPU selection | Requesting more than one vCPU under AVF gives the VM all available host cores rather than the exact count chosen in Settings. The CPU count setting has full effect on the QEMU backend only. |
| Storage | Size cannot be changed after setup without a full reset | The persistent ext4 overlay image (storage.img) is created at first-boot time and cannot be non-destructively resized later. Choose your storage size in the setup wizard. A future release may add live resize; for now a factory reset is required to change the allocation. |
| Background stability | Phantom-process killer terminates the VM (exit 137) on Android 12+ | Android 12 and later aggressively kill processes that are not direct children of an app's own process. QEMU is a subprocess of the foreground service; if Android classifies it as a phantom process, it sends SIGKILL (exit code 137). See the troubleshooting section below for the ADB command that disables this limit permanently. |
| Downloads sharing (AVF) | May silently do nothing, or crash QEMU's 9p worker on some ARMv9.2 devices | The virtio-9p driver used to expose the host Downloads folder is unstable on some hardware. On shipping Pixel AVF builds the share may be a silent no-op. On some ARMv9.2 devices (including the Pixel 10) the 9p worker in QEMU can crash and bring down the VM. If your VM crashes shortly after boot, disable Downloads sharing in Settings as the first diagnostic step. |
| X11 viewer: Wayland desktops | Wayland sessions do not render | The in-app X11 viewer connects to an Xvnc (X11) display. Wayland-native desktops (GNOME on Wayland, Plasma Wayland session, sway, Hyprland) start a compositor that does not render to an X display. Use XFCE, LXDE, or another X11 session, or force GNOME into its X11/Xorg session. |
| X11 viewer: compression | Raw encoding only - heavier bandwidth | ZRLE compression is currently disabled in the VNC client. Every frame is sent as uncompressed Raw pixels. At high resolutions on a high-DPI phone this means more bandwidth and slower screen updates. Choose a 720p or 900p resolution preset in the X11 viewer settings to compensate. |
| X11 viewer: right-click | External-mouse right-click exits fullscreen | A right-click from a paired Bluetooth or USB mouse is currently intercepted by the Android fullscreen gesture handler and dismisses fullscreen mode. As a workaround, use a two-finger touch to right-click; that gesture is passed through correctly to the VNC session. |
| X11 viewer: DPI | Server DPI changes need a VM restart | The guest Xvnc server is started with a fixed DPI argument. Changing the DPI setting in the app requires stopping and restarting the VM to take effect; hot-reloading is not supported. |
| First boot | Slower due to SSH host-key generation | On the very first boot, Dropbear generates RSA and ECDSA host keys. This is a one-time cost that typically adds 15-60 seconds on slower devices. Subsequent boots skip key generation and are noticeably faster. |
| CPU performance | TCG emulation is 5-20x slower than native for CPU-bound work | QEMU TCG translates ARM64 guest instructions to host ARM64 instructions in software. The overhead is highest for workloads that execute many unique code paths (compilers, JVM startup, npm install). IO-bound and memory-bound workloads fare better. See Performance & why it's slow for full detail and tuning options. |
Troubleshooting
VM dies or "QEMU crashed (SIGKILL)" when I switch apps
This is Android's phantom-process killer, active on Android 12 and later. When the app is backgrounded, the OS may classify QEMU as a phantom process and send SIGKILL, producing exit code 137 in the diagnostic log.
The fix is a one-time ADB command sequence that persists across reboots. Run these from a PC with adb installed:
# Disable phantom-process monitoring persistently (survives reboots)
$ adb shell device_config set_sync_disabled_for_tests persistent
$ adb shell device_config put activity_manager max_phantom_processes 2147483647
$ adb shell settings put global settings_enable_monitor_phantom_procs falseIf you have root on-device, the equivalent commands via su:
# On-device with root
$ su -c "device_config set_sync_disabled_for_tests persistent"
$ su -c "device_config put activity_manager max_phantom_processes 2147483647"
$ su -c "setprop persist.sys.fflag.override.settings_enable_monitor_phantom_procs false"device_config writes to the device_config namespace backed by Settings.Config. Setting set_sync_disabled_for_tests persistent prevents subsequent OTA flag pushes from reverting your values. The three properties together raise the phantom-process cap to Integer.MAX_VALUE and disable the monitor that enforces it.
It's slow. Can I enable KVM?
Not on the QEMU backend - KVM requires /dev/kvm access, which needs root. If you have a Pixel 8 or later (pKVM), switch to the AVF backend for near-native CPU speed. On any other device, the Performance page covers the TCG tuning options already applied (multi-threaded TCG, larger TB cache, iothread for disk I/O) and sets realistic expectations.
QEMU crashes with a hint about "Downloads sharing is unstable"
This is the virtio-9p crash on certain ARMv9.2 devices, including the Pixel 10. Open Settings inside Podroid and disable Downloads sharing. The crash will stop. The underlying 9p driver instability is an open issue in the QEMU build for those chips.
AVF stops on boot with reason=5 / STOP_REASON_REBOOT
This is a known issue on some Pixel 8, 8a, and 9 units where the pKVM firmware raises a stop event before the guest kernel finishes booting. To diagnose: enable Verbose AVF logging in Settings, reproduce the boot failure, then use Export diagnostic log to capture the output. While investigating, switch the Backend setting to QEMU to continue using the app.
VM won't start / stuck on "Starting"
Two timeouts govern boot: QEMU fails and surfaces an error if it cannot create its Unix sockets within 10 seconds (this usually means a stale socket file from a previous crash - try a force-stop and re-open). If sockets open but the guest never emits the Ready! marker, a 60-second boot timeout fires and the app declares the boot failed. In either case, go to Settings → Export diagnostic log and inspect console.log; the last few lines usually show exactly where the guest stalled.
First boot is very slow
Expected. Dropbear generates RSA and ECDSA host keys on the first boot, which takes 15-60 seconds on low-end hardware under TCG emulation. Once the keys exist on the persistent overlay they are never regenerated; subsequent boots skip this step entirely.
Right-click exits fullscreen when I use a mouse
This is a known limitation of the X11 viewer: Android's fullscreen gesture handler intercepts the right mouse button before it reaches the VNC client. Use a two-finger touch gesture to right-click instead - that path bypasses the gesture handler and is delivered correctly to the guest X session.
X11 is blurry or laggy
The VNC client uses uncompressed Raw encoding (ZRLE is currently disabled), so high resolutions generate large frame payloads. Open the X11 viewer settings and pick a lower resolution preset (720p or 900p are good starting points). If you are on AVF, the latency should be much lower than on QEMU; on QEMU, latency will scale with how busy the TCG threads are.
I changed RAM or CPU count and nothing happened
RAM and CPU count are passed to QEMU at launch time and cannot be hot-changed. Stop the VM from the main screen, then start it again - the new values will be used. Port-forward rules and SSH toggle changes take effect without a restart.
Podroid is free software (GPL). Docs for v1.2.1. Found something inaccurate? Open an issue.