A minimal and customizable Docker image running the Android emulator as a service.

中文: README.zh-CN.md

Current version: 1.1.0

• Features
• Description
• Usage
• See also

• Minimal Alpine based image bundled with the Android emulator and KVM support.
• Bundles the Java Runtime Environment 11 in the image.
• Customizable Android version, device type and image types.
• Port-forwarding of emulator and ADB on the container network interface built-in.
• Emulator images are wiped each time the emulator re-starts.
• Runs headless, suitable for CI farms. Compatible with scrcpy to remotely control the Android screen.
• Optional browser access through noVNC for viewing and interacting with the emulator without a local GUI client.

The focus of this project is to provide a size-optimized Docker image bundled with the minimal amount of software required to expose a fully functionning Android emulator that's remotely controllable over the network. This image only contains the Android emulator itself, an ADB server used to remotely connect into the emulator from outside the container, and QEMU with libvirt support.

You can build this image without the Android SDK and without the Android emulator to make the image smaller. Below is a size comparison between some of the possible build variants.

By default, a build will bundle the Android SDK, platform tools and emulator with the image.

with docker-compose:

docker compose up android-emulator

The default compose service also exposes noVNC on 127.0.0.1:6080.

or with GPU acceleration

docker compose up android-emulator-cuda

or for example with GPU acceleration and google playstore

docker compose up android-emulator-cuda-store

with only docker

docker build -t android-emulator .

To run google_apis_playstore image, you need to have same adbkey between emulator and client.

You can generate one by running adb keygen adbkey, that generates 2 files - adbkey and adbkey.pub.

override them inside ./keys directory.

Once the image is built, you can mount your KVM driver on the container and expose its ADB port.

Ensure 4GB of memory and at least 8GB of disk space for API 33.

docker run -it --rm --device /dev/kvm -p 5555:5555 android-emulator

All avd save in docker dir /data, name for avd is android

docker run -it --rm --device /dev/kvm -p 5555:5555 -v ~/android_avd:/data android-emulator

The ADB server in the container will be spawned automatically and listen on all interfaces in the container. After a few seconds, once the kernel has booted, you will be able to connect ADB to the container.

adb connect 127.0.0.1:5555

Additionally, you can use scrcpy to control the screen of the emulator remotely. To do so, you simply have to connect ADB and run it locally.

By default, the emulator runs with a Pixel preset (1080x1920).

scrcpy

The compose services in this repository can also publish the emulator window through noVNC. This avoids installing a local GUI client on the host and is useful when you only need a browser.

Start one of the bundled services:

docker compose up --build android-emulator

or

docker compose up --build android-emulator-cuda

Once the container is running and the emulator has booted, open:

http://127.0.0.1:6080/vnc.html

Notes:

• 5555 remains available for adb connect 127.0.0.1:5555.
• The compose file enables noVNC with ENABLE_NOVNC=true.
• The virtual display size can be adjusted with DISPLAY_WIDTH, DISPLAY_HEIGHT, and DISPLAY_DPI.

It is possible to customize the API level (Android version) and the image type (Google APIs vs PlayStore) when building the image.

By default, the image will build with API 33 with support for Google APIs for an x86_64 architecture.

This can come in handy when integrating multiple images as part of a CI pipeline where an application or a set of applications need to be tested against different Android versions. There are 2 variables that can be specified at build time to change the Android image.

• API_LEVEL - Specifies the API level associated with the image. Use this parameter to change the Android version.
• IMG_TYPE - Specifies the type of image to install.
• ARCHITECTURE Specifies the CPU architecture of the Android image. Note that only x86_64 and x86 are actively supported by this image.

The below example will install Android Pie with support for the Google Play Store.

docker build \
  --build-arg API_LEVEL=28 \
  --build-arg IMG_TYPE=google_apis_playstore \
  --build-arg ARCHITECTURE=x86 \
  --tag android-emulator .

DISABLE_ANIMATION=false

DISABLE_HIDDEN_POLICY=false

SKIP_AUTH=true

ENABLE_NOVNC=false

DISPLAY_WIDTH=1080

DISPLAY_HEIGHT=1920

DISPLAY_DPI=160

MEMORY=8192

CORES=4

EXTRA_FLAGS="-no-metrics -no-audio -partition-size=8192"

It might be sometimes useful to have the entire Android SDK folder outside of the container (stored on a shared distributed filesystem such as NFS for example), to significantly reduce the size and the build time of the image.

To do so, you can specify a specific argument at build time to disable the download and installation of the SDK in the image.

docker build -t android-emulator --build-arg INSTALL_ANDROID_SDK=0 .

You will need mount the SDK in the container at /opt/android.

docker run -it --rm --device /dev/kvm -p 5555:5555 -v /shared/android/sdk:/opt/android/ android-emulator

Different pre-built images of docker-android exist on Docker Hub. Each image variant is tagged using its the api level and image type. For example, to pull an API 33 image, you can run the following.

docker pull halimqarroum/docker-android:api-33

• The alpine-android project which is based on a different Alpine image.
• The docker-android project which offers a WebRTC interface to an Android emulator.