docker-android: an Android emulator inside a container, driven by environment variables

The problem docker-android removes is emulator provisioning, not emulator performance

Setting up an Android emulator on a build machine means installing the SDK, accepting licences, creating an AVD, picking a system image, and keeping all of that aligned with the API level your tests run against. docker-android turns that into a container start. The README describes the project as a docker image built to be used for everything related to Android, covering application development and testing for native, web and hybrid apps. The audience is therefore mobile engineers, QA teams running Appium or Espresso suites, and platform teams that need an emulator reachable over the network rather than attached to a developer's laptop. The device list is deliberately finite: the README names Samsung Galaxy S10, S9, S8, S7 Edge, S7 and S6, Nexus 4, 5, One and S, plus the Nexus 7 and Pixel C tablets. If your test matrix needs a device profile outside that list, you are outside what the project documents.

One container, one emulator, several side services

The architecture is a single image that boots an Android emulator process and exposes it three ways. First, adb: the README lists the ability to control the emulator from outside the container by using adb connect, so the emulator is not a black box. Second, a web view: with WEB_VNC enabled, noVNC serves the emulator screen on port 6080, which is how you see what is happening inside the container. Third, logs: the project supports a log-sharing feature where logs are reachable from a web UI, configured through the custom configurations document rather than the quick start. The images are also integrated with cloud platforms (Azure, AWS, GCP) and with Genymotion Cloud, and a separate image tag named mcp carries an MCP server that the README marks as beta. Android versions run from 9.0 (API 28) through 14.0 (API 34), each with its own image tag. The emulator skins come from Android Studio and the Samsung Developer website, so the visual chrome is not something the project draws itself.

Running it: one docker run, two environment variables that matter

The quick start is short. Confirm virtualisation is available on the host with apt install cpu-checker followed by kvm-ok, then start the container: 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 for the screen, and check readiness with docker exec -it android-container cat device_status. Two details are easy to miss. The --device /dev/kvm flag is not optional in practice, because the emulator needs hardware acceleration. And the default behaviour destroys the emulated device when the container restarts, so persistence requires mounting a volume at /home/androidusr, for example docker run -v data:/home/androidusr budtmo/docker-android:emulator_11.0. Image tags follow two shapes: budtmo/docker-android:emulator_11.0 tracks the latest release for that Android version, while emulator_11.0_<release_version> pins a specific one. For CI, pin the release-specific tag; the floating tag will move under you on the next push. The README also states plainly that the image runs under Ubuntu OS only, and that macOS and Windows users need a virtual machine supporting virtualisation with Ubuntu inside it.

KVM is the hard dependency, and WSL2 is the awkward middle case

Everything about this project rests on /dev/kvm being available to the container. On a Linux host that is a kernel module and a permissions question. On Windows 11 the README documents a WSL2 path that is more involved than the quick start suggests: add your user to the kvm group with sudo usermod -a -G kvm ${USER}, then add a boot command to /etc/wsl.conf, command = /bin/bash -c 'chown -v root:kvm /dev/kvm && chmod 660 /dev/kvm', which reassigns /dev/kvm to the kvm group rather than root on startup. Separately, notepad $env:USERPROFILE\.wslconfig needs nestedVirtualization=true under a [wsl2] section, and the README notes that flag is Windows 11 only. Then wsl --shutdown. The README also warns that if this does not work you may have an old WSL version, in which case the .wslconfig step is skipped and everything goes into /etc/wsl.conf including the [wsl2] flag. That is a lot of host configuration for a tool whose selling point is one command. If your CI runners are cloud VMs, check that the instance type exposes nested virtualisation before you design around this.

Where it is the wrong tool, and what Genymotion changes

docker-android is the wrong choice when you do not control the host kernel. macOS and Windows users are told to run a virtualised Ubuntu VM first, which means the container is the second layer of virtualisation, not the first. It is also the wrong choice when you need a device profile outside the documented list, or when you need many emulators in parallel, since each container carries its own emulator and the resource cost is per container. Genymotion is the alternative the README itself points at, and the difference is architectural rather than cosmetic. Genymotion Cloud is a hosted service: the README frames it for people who do not have the resources to maintain the simulator or to buy machines, and who need different device profiles. With docker-android you own the host, the KVM device and the emulator lifecycle. With Genymotion the emulator runs on someone else's infrastructure and docker-android acts as an integration point, documented for Genymotion SAAS, AWS, GCP and Alibaba Cloud. The trade is control and cost structure against operational burden; if you cannot guarantee KVM on your own hardware, the hosted route removes the constraint you cannot fix.

Maintenance cost and the licence question the repository does not answer

The release cadence visible in the supplied material is roughly monthly: v3.5.2-p0 in June 2026, v3.6.0-p0 in August, v3.7.0-p0 in September, with the last push to master on 2026-09-09. The -p0 suffix on every tag suggests a patch-level release convention, and it means there is a stream of tags to track rather than a single stable line. Upgrading is not free: Android version tags map to API levels, so moving from emulator_11.0 to emulator_14.0 changes the API level your tests run against, and that can break tests independently of anything the project changed. Pin the full release-specific tag and treat an Android version bump as a deliberate migration. On licensing, the repository metadata reports NOASSERTION, which means GitHub could not identify a standard licence from the repository contents. The README does not state a licence in the material provided. That is a real obstacle if you plan to redistribute the image or build it into a product, and it is not something this article can resolve. Read the repository's licence file directly and get your own answer before you depend on it commercially.

What to verify before you put it in a pipeline

Start with the host, not the image. Run kvm-ok on the exact machine class your CI uses, and confirm the container can open /dev/kvm; if that fails, nothing else in this article matters. Next, pin the release-specific tag (emulator_11.0_<release_version> form) rather than the floating one, and record which Android version and API level that tag corresponds to, because your test suite is coupled to it. Then decide on persistence explicitly: the default wipes the emulated device on restart, so if your tests install state that must survive a restart, mount the volume at /home/androidusr. Finally, check the two features the README leaves to separate documents: log sharing and the MCP server, the latter labelled beta. Both are described as configuration work in the custom configurations and use-case documents, not in the quick start, so budget time for reading them rather than assuming they work out of the box. The device_status file inside the container is your readiness probe; wire it into your pipeline instead of sleeping and hoping.

Editorial conclusion

Adopt docker-android if you run Linux CI machines with KVM and need a reproducible emulator endpoint that a test framework or a remote viewer can attach to. Do not adopt it if your build agents are macOS or Windows without a virtualised Ubuntu host, or if you need an unambiguous licence for redistribution. Before committing, verify that the host exposes /dev/kvm, that the image tag you pin matches the Android API level your tests target, and that the licence terms for the tag you pull are acceptable to your legal reviewers.

Official sources

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