docker-android README

The project's README from github.com/budtmo/docker-android. As one markdown file: README.md.

Paypal Donate PRs Welcome codecov Join the chat at https://gitter.im/budtmo/docker-android GitHub release

Docker-Android is a docker image built to be used for everything related to Android. It can be used for Application development and testing (native, web and hybrid-app).

Advantages of using this project

  1. Emulator with different device profile and skins, such as Samsung Galaxy S6, LG Nexus 4, HTC Nexus One and more.
  2. Support vnc to be able to see what happen inside docker container
  3. Support log sharing feature where all logs can be accessed from web-UI
  4. Ability to control emulator from outside container by using adb connect
  5. Integrated with other cloud solutions, e.g. Genymotion Cloud
  6. It can be used to build Android project
  7. It can be used to run unit and UI-Test with different test-frameworks, e.g. Appium, Espresso, etc.
  8. It support mcp server (beta-version)

List of Docker-Images

Android API Image with latest release version Image with specific release version
9.0 28 budtmo/docker-android:emulator_9.0 budtmo/docker-android:emulator_9.0_
10.0 29 budtmo/docker-android:emulator_10.0 budtmo/docker-android:emulator_10.0_
11.0 30 budtmo/docker-android:emulator_11.0 budtmo/docker-android:emulator_11.0_
12.0 32 budtmo/docker-android:emulator_12.0 budtmo/docker-android:emulator_12.0_
13.0 33 budtmo/docker-android:emulator_13.0 budtmo/docker-android:emulator_13.0_
14.0 34 budtmo/docker-android:emulator_14.0 budtmo/docker-android:emulator_14.0_
- - budtmo/docker-android:genymotion budtmo/docker-android:genymotion_
- - budtmo/docker-android:mcp budtmo/docker-android:mcp_

List of Devices

Type Device Name
Phone Samsung Galaxy S10
Phone Samsung Galaxy S9
Phone Samsung Galaxy S8
Phone Samsung Galaxy S7 Edge
Phone Samsung Galaxy S7
Phone Samsung Galaxy S6
Phone Nexus 4
Phone Nexus 5
Phone Nexus One
Phone Nexus S
Tablet Nexus 7
Tablet Pixel C

Requirements

  1. Docker is installed on your system.

Quick Start

  1. If you use Ubuntu OS on your host machine, you can skip this step. For OSX and Windows OS user, you need to use Virtual Machine that support Virtualization with Ubuntu OS because the image can be run under Ubuntu OS only.

  2. Your machine should support virtualization. To check if the virtualization is enabled is:

    sudo apt install cpu-checker
kvm-ok

  3. Run Docker-Android 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

  4. Open http://localhost:6080 to see inside running container.

  5. To check the status of the emulator

    docker exec -it android-container cat device_status

Persisting data

The default behaviour is to destroy the emulated device on container restart. To persist data, you need to mount a volume at /home/androidusr: docker run -v data:/home/androidusr budtmo/docker-android:emulator_11.0

WSL2 Hardware acceleration (Windows 11 only)

Credit goes to Guillaume - The Parallel Interface blog

Microsoft - Advanced settings configuration in WSL

  1. Add yourself to the kvm usergroup.

    sudo usermod -a -G kvm ${USER}

  2. Add necessary flags to /etc/wsl.conf to their respective sections.

    [boot]
command = /bin/bash -c 'chown -v root:kvm /dev/kvm && chmod 660 /dev/kvm'

    Then, using PowerShell, open a notepad on notepad $env:USERPROFILE\.wslconfig. Inside, put these other flags:

    [wsl2]
nestedVirtualization=true

  3. Restart WSL2 via CMD prompt or Powershell

    wsl --shutdown

command = /bin/bash -c 'chown -v root:kvm /dev/kvm && chmod 660 /dev/kvm' sets /dev/kvm to kvm usergroup rather than the default root usergroup on WSL2 startup.

nestedVirtualization flag is only available to Windows 11.

If this setup does not work, you may have an old WSL version. In that case, ignore \.wslconfig and put everything on /etc/wsl.conf, including the [wsl2] flag.

Use-Cases

  1. Build Android project
  2. UI-Test with Appium
  3. Control Android emulator on host machine
  4. SMS Simulation
  5. Jenkins
  6. Deploying on cloud (Azure, AWS, GCP)

Custom-Configurations

This document contains information about configurations that can be used to enable some features, e.g. log-sharing, etc.

Genymotion

For you who do not have ressources to maintain the simulator or to buy machines or need different device profiles, you can give a try by using Genymotion SAAS. Docker-Android is integrated with Genymotion on different cloud services, e.g. Genymotion SAAS, AWS, GCP, Alibaba Cloud. Please follow this document for more detail.

Emulator Skins

The Emulator skins are taken from Android Studio IDE and Samsung Developer Website

USERS

docker-android-users

PRO VERSION

Due to high requests for help and to be able to actively maintain the projects, the creator has decided to create docker-android-pro. Docker-Android-Pro is a sponsor based project which mean that the docker image of pro-version can be pulled only by active sponsor.

The differences between normal version and pro version are:

Feature Normal Pro Comment
user-behavior-analytics Yes No -
proxy No Yes Set up company proxy on Android emulator on fly
language No Yes Set up language on Android emulator on fly
Newer Android version No Yes Support other newer Android version e.g. Android 15, Android 16, etc
root-privileged No Yes Able to run command with security privileged
headless-mode No Yes Save resources by using headless mode
Selenium 4.x integration No Yes Running Appium UI-Tests againt one (Selenium Hub) endpoint for Android- and iOS emulator(s) / device(s)
multiple Android-Simulators No Yes (soon) Save resources by having multiple Android-Simulators on one docker-container
Google Play Store No Yes (soon) -
Video Recording No Yes (soon) Helpful for debugging

This document contains detail information about how to use docker-android-pro.

SPONSORS

Swiftproxy

Swiftproxy — Swiftproxy provides high-quality residential proxies for Android testing, automation, and location-based workflows. With 90M+ residential IPs, HTTP(S)/SOCKS5 support, flexible targeting, and non-expiring traffic, Swiftproxy helps users test apps and online services from different locations. Try Swiftproxy for free today and get 10% off with code PROXY90.

Learn more about Swiftproxy →

Rapidproxy

RapidProxy — RapidProxy is a high-performance proxy provider built for automation and multi-account operations, offering clean residential proxies and native static ISP IPs. Access 90 million+ residential IPs worldwide, with intelligent rotation, sticky sessions, and support for high-concurrency requests. Ideal for web scraping, browser automation, social media account management, e-commerce, and bulk account registration. Residential proxies start at just $0.55/GB, with bandwidth that never expires. Use code RAPID10 for 10% off.

Learn more about Rapidproxy →

LICENSE

See License

docker-android (budtmo/docker-android)

Searching Database…

16K ·GitHub
Docker-android
What is this?Docker-Android is a Docker image that ships a complete Android emulator in a container, built for Android app development and testing — native, web and hybrid apps.
Is it an app I install on a phone, or what exactly am I running?You run a Docker container that emulates a real device profile with a skin (Samsung Galaxy S6, Nexus 4 and more), watch its screen via noVNC/VNC in a browser, and read logs from a built-in web-UI.
How do I get it running?Install Docker, then pull a versioned image and run it — for example budtmo/docker-android:emulator14.0. Images exist per Android release from 9.0 to 14.0, plus a genymotion variant and a beta mcp variant.
Do I need anything besides Docker on my machine?Just a CPU with virtualization enabled — the emulator needs it to run.
What happens to my emulated device if the container restarts?By default it is destroyed on restart. To keep your data, mount a volume at /home/androidusr.
Will it run on my Mac or Windows laptop, or only on Linux?Only on Ubuntu: macOS and Windows users need a VM running Ubuntu. On Windows 11 you can use WSL2 with hardware acceleration instead — the nestedVirtualization flag is Windows 11-only.
Can I run this on a cloud server or in CI instead of my own machine?Yes — the listed use-cases include deploying on Azure, AWS and GCP, running under Jenkins, and controlling the emulator from the host via adb connect.
Does it collect anything from me?The free image ships with user-behavior analytics enabled; the sponsor-based pro version removes them.
Which devices and Android versions can it emulate?Device profiles and skins cover phones and tablets like Samsung Galaxy S6 through S10, the Nexus 4/5/7/S/One line and Pixel C. Ready-made images span Android 9.0 to 14.0; versions like Android 15 and 16 are reserved for the pro image.
Can I run automated tests against it?Yes, that is one of its main use-cases: unit and UI tests with frameworks such as Appium and Espresso, driven from outside the container via adb connect, plus a Jenkins integration for CI pipelines.
What is the deal with the pro version?The pro image is sponsor-based: only active sponsors can pull it. Compared to the free version it adds on-the-fly proxy and language setup, newer Android releases, root-privileged commands, headless mode and Selenium 4.x integration — while multiple simulators, Google Play Store and video recording are listed as coming soon.
What is the MCP image for?Alongside the emulator images there is a budtmo/docker-android:mcp image exposing an MCP server in beta, so AI agents can work with the emulated device — the project pitches itself as Android in Docker with MCP server and AI-agent support.
What are similar projects?opensre, prowler, redStackPRO, artifact-server, neckbeard, omnigraph, pulumi, localstack
Which topics is it in?jenkins, selenium, gcp, azure, emulator, virtualization, aws, vllm, ollama, mobile-app, kubernetes, testing
Creator
budtmo
Size
237.7 MB
Stars
16K
Updated
CommitOct 12Releasev3.8.0-p1Oct 09
Age
9y
Commits · 90 Days