budtmo/docker-android: an Android emulator inside a Docker container

What docker-android is for, and who actually needs it

The README describes Docker-Android as a docker image built to be used for everything related to Android, and lists application development and testing of native, web and hybrid apps as the targets. The practical audience is narrower than that sentence suggests. If you maintain an Android test suite that has to run unattended on a build server, this project removes the step where you install the SDK, create an AVD and keep it alive between jobs. You pull an image tagged for an Android version, start it, and the emulator is already booting behind a VNC server.

The supported tags map to Android releases rather than to your app: emulator_9.0 through emulator_14.0, covering API levels 28 to 34, plus a genymotion image and an mcp image. The README also lists twelve device profiles, from a Nexus One up to a Samsung Galaxy S10, plus two tablets. That list is the ceiling. If your test matrix includes a device that is not there, the image will not reproduce it for you.

How the container runs the emulator and exposes it

The architecture is a single long-lived container. Inside it, the Android emulator runs against the host's KVM device, which is why the quick start command passes --device /dev/kvm. A VNC server is started when WEB_VNC is set, and the README points you at port 6080 to see inside the running container through a browser. The same container can be reached from outside with adb connect, which the README lists as a feature, so a test runner on the host or in another container can drive the device over the network instead of through the image's own shell.

Two smaller mechanisms matter in practice. The container writes a device_status file that you can read with docker exec, which gives a cheap readiness check for CI scripts. And log sharing, described in the custom configurations document, serves logs over the web UI rather than making you attach to the container.

The mcp image is the newest piece and the README marks MCP support as a beta version. Treat it as an addition to the same container model, not a separate product.

Installing docker-android and starting a first emulator

The only stated requirement is Docker on the host. The README is explicit that the image runs under Ubuntu only, and that OSX and Windows users need a virtual machine with virtualization support running Ubuntu. Before pulling anything, confirm the host exposes KVM:

sudo apt install cpu-checker
kvm-ok

If kvm-ok reports that KVM acceleration can be used, start a container. This command runs it detached, publishes the VNC port, selects a device profile and enables the web VNC view:

docker run -d -p 6080:6080 -e EMULATOR_DEVICE="Samsung Galaxy S10" -e WEB_VNC=true --device /dev/kvm --name android-container budtmo/docker-android:emulator_11.0

Open http://localhost:6080 and you should see the emulator's screen. To confirm the device finished booting rather than assuming it did, read the status file the container writes:

docker exec -it android-container cat device_status

One behaviour to plan around: the README states that the emulated device is destroyed on container restart by default. Mounting a volume at /home/androidusr is the documented way to keep state between runs:

docker run -v data:/home/androidusr budtmo/docker-android:emulator_11.0

The KVM requirement is the real adoption boundary

Everything above assumes a Linux host with hardware virtualization exposed to the container. That is not a configuration detail, it is the boundary of the project. On macOS and Windows the README does not offer a native path; it tells you to run a virtualized Ubuntu machine and work inside it. That nesting costs performance and adds a layer that can fail on its own, and it means the developer laptop experience is materially worse than the CI experience.

Windows 11 users get a documented workaround through WSL2, and the README is honest about its limits. It requires adding yourself to the kvm group, a boot command in /etc/wsl.conf that chowns /dev/kvm to root:kvm, and nestedVirtualization=true in .wslconfig, followed by wsl --shutdown. The README notes that nestedVirtualization is available only on Windows 11 and that older WSL versions should put the [wsl2] flag in /etc/wsl.conf instead. This is a chain of host-level settings, not a flag on the docker run command, and it is the most likely place for a first attempt to fail.

ARM hosts are a second gap. The README's image table and device table are the only coverage it gives, and neither addresses arm64. If you were planning to run this on an Apple Silicon machine or an ARM CI runner, the documentation offers nothing to confirm it works.

docker-android versus redroid and Waydroid

The closest alternatives people search for are redroid and Waydroid, and the difference is what runs inside the container. Docker-android runs the standard Android emulator, the same QEMU-based emulator Android Studio uses, against KVM. Redroid runs Android natively as a container workload on the host kernel, without a full emulator. Waydroid does something similar for Linux desktops, running Android in a container on the host.

That distinction decides your choice. Because docker-android uses the emulator, it inherits the emulator's device profiles and skins, which is what lets the README offer a Galaxy S10 or a Nexus 7 as a named target. A native-container approach does not give you a specific phone's characteristics; it gives you Android running fast. It also means docker-android pays the emulator's startup and memory cost on every cold container. If your goal is a fast, cheap Android runtime for a single app, the emulator is overhead. If your goal is a test matrix that names devices and Android versions, the emulator is the point.

A second alternative sits inside the project's own orbit: the README documents integration with Genymotion Cloud and points at a genymotion image, aimed at teams without the resources to maintain simulators or buy machines. That is the hosted route, and it moves the KVM problem off your hardware.

Maintenance, image tags and licence questions to settle first

The repository is not archived, and the last push was on 2026-09-09, so the codebase is being touched recently. Releases are frequent and follow a versioned tag scheme: v3.7.0-p0 on 2026-09-01, v3.6.0-p0 on 2026-08-04, v3.5.2-p0 on 2026-06-24. The image naming in the README supports pinning, with emulator_11.0_<release_version> as the form for a specific release. Pin the tag in CI. Using the unversioned emulator_11.0 tag means a rebuild can change the emulator under your tests without any change on your side.

Upgrade cost is dominated by the Android version, not by the project's own release cadence. Moving from emulator_11.0 to emulator_14.0 changes the API level your tests run against, which can break tests for reasons that have nothing to do with docker-android. Treat image bumps as test-matrix changes.

On licensing, the repository metadata reports NOASSERTION and there is a LICENSE.md at the top level, but the README does not state which licence governs the images or the bundled Android SDK components. That is worth resolving before commercial distribution, and it is a question for your legal team rather than something this article can answer.

Editorial conclusion

Adopt budtmo/docker-android if you run Android UI tests or builds on Linux CI machines with KVM and want the emulator, VNC and Appium in one image. Do not adopt it on macOS or Windows hosts, where the README requires a virtualized Ubuntu VM, or on ARM boards, which the device and image tables do not cover. Before committing, verify that /dev/kvm is usable on the target host, that the device profile you need is in the supported list, and which licence applies to the image you pull, since the repository states NOASSERTION and the README does not settle the question.

Frequently asked questions

Official sources

1. budtmo/docker-android on GitHub
2. Issues
3. README
4. Releases