--- title: "Android images with the machine executor" description: "Use the Android machine image on the Linux machine executor with the Android orb or manual configuration, and review resource classes and preinstalled tools." platform: "Cloud, Server" doc_version: "unversioned" last_updated: "2026-10-15" cloud_plans: "Free, Performance, Scale" version_control: "All supported providers" --- > For current CircleCI product defaults, deprecated patterns, and Cloud/Server differences, see [AGENTS.md](https://circleci.com/docs/AGENTS.md). > > For the complete documentation index and site structure, see [llms.txt](https://circleci.com/docs/llms.txt). # Android images with the machine executor **Cloud plans:** Free, Performance, Scale **Version control:** [All supported providers](https://circleci.com/docs/guides/integration/version-control-system-integration-overview/) ## Overview You access the Android machine image through the [Linux Machine Executor](https://circleci.com/docs/reference/configuration-reference/#available-linux-machine-images-cloud), like other Linux machine images on CircleCI. The Android machine image supports nested virtualization and x86 Android emulators, so you can use it for Android UI testing. It also comes with the Android SDK pre-installed. ## Using the Android machine image You can configure the Android image in your configuration using [Orbs](https://circleci.com/docs/orbs/use/orb-intro/), or manually. The Android orb simplifies your configuration. More complex and custom configurations may work better with manual configuration instead of the orb. This document covers both use cases. Refer to the [Examples](#examples) section below for more details. ## Available resource classes ### Gen1 | Class | vCPUs | RAM | Disk Size | Cloud | Server | | --- | --- | --- | --- | --- | --- | | `medium` | 2 | 7.5 GB | 150GB | **Yes** | **Yes** | | `large` | 4 | 15 GB | 150GB | **Yes** | **Yes** | | `xlarge` | 8 | 32 GB | 150GB | **Yes** | **Yes** | | `2xlarge` | 16 | 64 GB | 150GB | **Yes** | **Yes** | | `2xlarge+` | 32 | 64 GB | 150GB | **Yes** | **Yes** | ### Gen2 | Class | vCPUs | RAM | Disk Size | Cloud | Server | | --- | --- | --- | --- | --- | --- | | `medium.gen2` | 2 | 8 GiB | 150GB | **Yes** | **No** | | `large.gen2` | 4 | 16 GiB | 150GB | **Yes** | **No** | | `xlarge.gen2` | 8 | 32 GiB | 150GB | **Yes** | **No** | | `2xlarge.gen2` | 16 | 64 GiB | 150GB | **Yes** | **No** | | `2xlarge+.gen2` | 32 | 128 GiB | 150GB | **Yes** | **No** | ### View resource usage To view the compute resource usage for the duration of a job in the CircleCI web app: 1. In the [CircleCI web app](https://app.circleci.com), select your org from the org cards on your user homepage. 2. Select **Pipelines** from the sidebar and locate your pipeline from the list. You can use the project, branch, date, and status search options to help. 3. Select the job you want to access by selecting the job name. 4. Select the **Resources** tab to view CPU and RAM usage for the duration of the job. You can use these insights to decide whether to make changes to the job’s configured resource class. > **Image:** Resources tab Figure 1. Resources tab in web app for a job ## Android machine image generations ### Gen2 Resource classes running on gen2 infrastructure offer significant performance and cost improvements over their gen1 equivalents. #### Performance improvements Using more modern compute, gen2 instances deliver up to 47% faster performance compared to gen1 equivalents. On a per-resource-class basis, gen2 pricing can be higher or lower than its gen1 equivalent. See our [Pricing Page](https://circleci.com/pricing/price-list/) for details. #### Using gen2 All Android gen1 resource classes are also available as gen2. Gen2 images use the `current` tag instead of the `default` tag used by gen1, to stay consistent with the Linux VM tagging convention. To use a gen2 resource class, specify the `current` tag along with a `large.gen2` or equivalent resource class in your job configuration: ```yaml version: 2.1 jobs: build: machine: image: android:current resource_class: large.gen2 steps: # ... steps for your job ``` Gen2 resource classes for the Android machine image are available on CircleCI Cloud only. ## Pre-installed software View the latest update announcement on our [Discuss](https://discuss.circleci.com/c/ecosystem/circleci-images/) page for a list of current pre-installed software. ## Examples The following examples show how to use the Android machine image, both with and without orbs. ### Simple orb usage The below sample uses the Android orb to run a single job. Make sure to replace any placeholder versions in the example. ```yaml # .circleci/config.yaml version: 2.1 orbs: android: circleci/android@3.1.0 # https://circleci.com/developer/orbs/orb/circleci/android for latest version workflows: test: jobs: # This job uses the Android machine image by default - android/run-ui-tests: # Use pre-steps and post-steps if necessary # to execute custom steps before and after any of the built-in steps system-image: system-images;android-29;default;x86 executor: name: android/android_machine resource-class: large tag: default ``` ### More complex orb usage This example shows how you can use more granular orb commands to achieve what the [start-emulator-and-run-tests](https://circleci.com/developer/orbs/orb/circleci/android#commands-start-emulator-and-run-tests) command does. Make sure to replace any placeholder versions in the example. ```yaml # .circleci/config.yml version: 2.1 orbs: android: circleci/android@3.1.0 # https://circleci.com/developer/orbs/orb/circleci/android for latest version jobs: test: executor: name: android/android_machine resource-class: large tag: default steps: - checkout # Create an AVD named "myavd" - android/create-avd: avd-name: myavd system-image: system-images;android-29;default;x86 install: true # By default, after starting up the emulator, a cache will be restored, # "./gradlew assembleDebugAndroidTest" will be run and then a script # will be run to wait for the emulator to start up. # Specify the "post-emulator-launch-assemble-command" command to override # the gradle command run, or set "wait-for-emulator" to false to disable # waiting for the emulator altogether. - android/start-emulator: avd-name: myavd no-window: true restore-gradle-cache-prefix: v1a # Runs "./gradlew connectedDebugAndroidTest" by default. # Specify the "test-command" parameter to customize the command run. - android/run-tests - android/save-gradle-cache: cache-prefix: v1a workflows: test: jobs: - test ``` ### No-orb example The following example uses the Android machine image _without_ the `circleci/android` [orb](https://circleci.com/developer/orbs/orb/circleci/android). These steps match what runs when you use the [`run-ui-tests` job](https://circleci.com/developer/orbs/orb/circleci/android#jobs-run-ui-tests) of the orb. ```yaml # .circleci/config.yml version: 2.1 jobs: build: machine: image: android:default # To optimize build times, we recommend "large" and above for Android-related jobs resource_class: large steps: - checkout - run: name: Create avd command: | SYSTEM_IMAGES="system-images;android-29;default;x86" sdkmanager "$SYSTEM_IMAGES" echo "no" | avdmanager --verbose create avd -n test -k "$SYSTEM_IMAGES" - run: name: Launch emulator command: | emulator -avd test -delay-adb -verbose -no-window -gpu swiftshader_indirect -no-snapshot -noaudio -no-boot-anim background: true - run: name: Generate cache key command: | find . -name 'build.gradle' | sort | xargs cat | shasum | awk '{print $1}' > /tmp/gradle_cache_seed - restore_cache: key: gradle-v1-{{ arch }}-{{ checksum "/tmp/gradle_cache_seed" }} - run: # run in parallel with the emulator starting up, to optimize build time name: Run assembleDebugAndroidTest task command: | export TERM=dumb ./gradlew assembleDebugAndroidTest - run: name: Wait for emulator to start command: | circle-android wait-for-boot - run: name: Disable emulator animations command: | adb shell settings put global window_animation_scale 0.0 adb shell settings put global transition_animation_scale 0.0 adb shell settings put global animator_duration_scale 0.0 - run: name: Run UI tests (with retry) command: | MAX_TRIES=2 run_with_retry() { n=1 until [ $n -gt $MAX_TRIES ] do echo "Starting test attempt $n" ./gradlew connectedDebugAndroidTest && break n=$[$n+1] sleep 5 done if [ $n -gt $MAX_TRIES ]; then echo "Max tries reached ($MAX_TRIES)" exit 1 fi } run_with_retry - save_cache: key: gradle-v1-{{ arch }}-{{ checksum "/tmp/gradle_cache_seed" }} paths: - ~/.gradle/caches - ~/.gradle/wrapper workflows: build: jobs: - build ``` ### Using the Android image on server Android machine images are only available on server installations on Google Cloud Platform (GCP). CircleCI Server 3.4+ supports Android machine images for installations on GCP. To use the Android image in your projects, set the `image` key to `android-default` in your jobs. ```yaml version: 2.1 jobs: my-job: machine: image: android-default steps: # job steps here ``` You can also use the Android orb, as shown above, for cloud. Your server administrator needs to import the orb first. You also need to define the `android-default` image for the machine executor, as shown in the example below, rather than using the default executor built into the orb. View the [CircleCI Server Orbs](https://circleci.com/docs/server-admin/latest/operator/managing-orbs/) page for instructions on importing orbs. This example shows how you can use granular orb commands to achieve what the [start-emulator-and-run-tests](https://circleci.com/developer/orbs/orb/circleci/android#commands-start-emulator-and-run-tests) command does. Make sure to replace any placeholder versions in the example. ```yaml # .circleci/config.yml version: 2.1 orbs: android: circleci/android@x.y.z # https://circleci.com/developer/orbs/orb/circleci/android for latest version jobs: test: machine: image: android-default steps: - checkout # Create an AVD named "myavd" - android/create-avd: avd-name: myavd system-image: system-images;android-29;default;x86 install: true # By default, after starting up the emulator, a cache will be restored, # "./gradlew assembleDebugAndroidTest" will be run and then a script # will be run to wait for the emulator to start up. # Specify the "post-emulator-launch-assemble-command" command to override # the gradle command run, or set "wait-for-emulator" to false to disable # waiting for the emulator altogether. - android/start-emulator: avd-name: myavd no-window: true restore-gradle-cache-prefix: v1a # Runs "./gradlew connectedDebugAndroidTest" by default. # Specify the "test-command" parameter to customize the command run. - android/run-tests - android/save-gradle-cache: cache-prefix: v1a workflows: test: jobs: - test ```