docker-androidlightweight Docker image

By /

docker-android is a lightweight and customizable Docker image with built-in Android emulator, KVM virtualization, and ADB debugging tools, which can be remotely controlled via scrcpy. Run it by running a simple command: docker run –device /dev/kvm -p 5555:5555 (Note: The original port number is a clerical error, corrected to the standard port format for Android debugging).
The image supports custom Android versions (such as API 33), integration with the Google Play Store, and external mounting of Android development kits (SDKs) for extreme lightweight (only 138MB of compressed packages without SDK integration).
Its core advantage is that it enables fast and consistent headless Android testing in CI/CD pipelines, saving time and resource costs in setting up environments.

In many scenarios, you don’t want to “open an emulator natively”, but you want an Android environment that can be repeated, batched, and remotely connected: for example, running UI tests in CI, providing emulator instances on the server, or having the test machine set up a fixed version of Android with one click.

HQarroum/docker-android is straightforward:
 Package the Android Emulator into a Docker image that is as streamlined and customizable as possible, let the emulator run as a “service” and expose the ADB over the network , where external machines can connect directly to control.

Minimal dependencies + remotely controllable emulator images

The README’s description emphasizes two points:

  1. Size-optimized: Install only the minimum components needed to “run and control remotely”.
  2. Remote controllable: The container comes with an ADB server and opens the port to the outside world. You can connect to the simulator outside adb connect of the container.

Its composition is also clearly written: the image only contains the Android emulator, ADB server, and QEMU with libvirt support (for virtualization-related capabilities).

Key features at a glance

The characteristics of the README column are very “engineered” and are basically for CI/remote running simulators:

  •  Thin image based on Alpine , supporting KVM acceleration (requires host provision /dev/kvm).
  •  Built-in JRE 11.
  • When building, you can select Android API version / device type / image type.
  • The container network interface has built-in port forwarding between the Emulator and ADB (externally direct connection).
  • The default is headless interface, suitable for CI farm; And it is compatible with scrcpy to control the screen remotely.
  • There is also a key behavior: the emulator restart wipes the mirrored data (more like a one-time test environment).

Mirror volume: Why it emphasizes “croppable”

The README gives a volume comparison of the different build variants (decompressed/compressed):

  • API 33 + Emulator：5.84 GB / 1.97 GB
  • API 32 + Emulator：5.89 GB / 1.93 GB
  • API 28 + Emulator：4.29 GB / 1.46 GB
  • Build without SDK and emulator: 414 MB / 138 MB

This explains its design ideas:
You can put the “heavy Android SDK” on external shared storage (NFS, etc.) and keep only the shell you need to run in the container, reducing build time and image size.

Start a remotely connected emulator

docker-compose starts

The README gives the compose a way to start:

docker compose up android-emulator

If you want GPU acceleration, there are also corresponding compose service name examples:

docker compose up android-emulator-cuda
# 以及带 playstore 的示例：
docker compose up android-emulator-cuda-store

Pure docker (KVM acceleration)

Build the image:

docker build -t android-emulator .

Run (hook the host KVM device into the container and map the ADB port):

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

Connecting ADB:

adb connect 127.0.0.1:5555

If you want to remotely “look at the screen and operate”, the README directly recommends scrcpy:

scrcpy

Two “real needs”

I don’t want to lose data every time I restart

Although the default restart will wipe, the README provides a way to persist AVD: mount the /data container.

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

To test different Android versions / different image types

Parameter control can be passed during construction:

  • API_LEVEL: The API level corresponding to the Android version
  • IMG_TYPE: Image type (such as Google APIs or Play Store)
  • ARCHITECTURE:CPU architecture (README mentions primary support for x86_64 / x86)

Example (with API 28 + Play Store, x86):

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

Play Store mirrored “ADB key” pits

README Special reminder: If you run google_apis_playstore an image, the in-container emulator needs to use the same set of adbkeys as your native adb client. It also gives the build method and requires it to be put in ./keys the directory override. ([GitHub][1])


adb keygen adbkey
生成 adbkey / adbkey.pub，然后放进 ./keys

More CI-oriented configuration items

The README exposes some running parameters (e.g., whether to disable animations, memory, number of CPU cores, whether to skip ADB authentication, etc.), and the typical use is to make CI more stable/faster.
For example, it lists:

  • DISABLE_ANIMATION
  • SKIP_AUTH
  • MEMORY
  • CORES
    etc.

Pull the Docker Hub pre-built image directly

If you don’t want to build locally, the README mentions that Docker Hub has pre-built images, tagged by API level/image type. Example:

docker pull halimqarroum/docker-android:api-33

Github：https://github.com/HQarroum/docker-android
Tubing:

Scroll to Top