android-emulator

android-emulator

End-to-end emulator management: install the necessary system image, create the AVD with the right profile, boot it cold, wait until it's actually ready, and stop it cleanly when done.

Configuration

{
  "androidCli": {
    "defaultProfile": "medium_phone",
    "systemImage": "system-images/android-34/google_apis/x86_64",
    "sdkChannel": "stable"
  }
}

Field	Purpose
androidCli.defaultProfile	Profile passed to android emulator create --profile=. Defaults to medium_phone when unset.
androidCli.systemImage	System image package to ensure is installed before creating the AVD.
androidCli.sdkChannel	stable, beta, or canary. Drives the --beta / --canary flag on android sdk install.

If unset, ask once on first creation and save.

Platform support

⚠️ Windows: android emulator is currently disabled on Windows. Detect via uname / OS env var first; if Windows, abort and instruct the user to:

• Use the Studio AVD Manager UI, or
• Use avdmanager + emulator from the SDK directly. Do not attempt android emulator commands on Windows.

Workflow

Create + boot from scratch

# 1. Ensure system image is installed
android emulator list                                        # is anything already there?
android sdk list 'system-images/android-'                    # what's available
android sdk install <systemImage>                            # install if missing

# 2. Pick a profile and create the AVD
android emulator create --list-profiles                      # show options
android emulator create --profile=<defaultProfile>           # creates with that profile

# 3. Boot
android emulator start <avd-name>

# 4. Wait until fully booted (don't deploy too early)
adb wait-for-device
adb shell 'while [ "$(getprop sys.boot_completed)" != "1" ]; do sleep 1; done'

After step 4, it's safe to hand off to android-deploy.

Start an existing AVD

android emulator list           # confirm name
android emulator start <name>
adb wait-for-device shell 'while [ "$(getprop sys.boot_completed)" != "1" ]; do sleep 1; done'

Stop

adb devices                     # find the emulator-XXXX serial
android emulator stop <serial>

android emulator stop takes the serial (e.g., emulator-5554), not the AVD name — easy to mix up.

Profile selection

Run android emulator create --list-profiles to see what's actually available on the user's machine. Common profiles include medium_phone, pixel_8, pixel_tablet, wear_round, tv_4k. Don't hardcode names — they evolve with the CLI.

If the user just says "make an emulator", default to androidCli.defaultProfile from config, or medium_phone if absent.

System image selection

System image packages follow system-images/android-<api>/<variant>/<abi>:

• <api> — API level. Default to the latest stable API the project actually targets (read from compileSdk in app/build.gradle.kts).
• <variant> — google_apis (Play services without Play Store), google_apis_playstore (with Play Store, signed builds only), aosp (no Google services).
• <abi> — x86_64 on x86 hosts, arm64-v8a on Apple Silicon.

For Apple Silicon, prefer arm64-v8a images for performance. x86_64 images run under emulation and are noticeably slower.

Operating rules

1. Always wait for boot before deploying. adb wait-for-device returns when the daemon is up, not when Android has finished booting. The sys.boot_completed poll is the correct gate.
2. Match ABI to host architecture. Apple Silicon → arm64-v8a. Cross-arch images work but are slow.
3. Don't pile up emulators. If the user's "make an emulator" intent overlaps with an existing one, ask before creating duplicates.
4. Stop with serial, create with name. This is the consistent footgun — start <name>, stop <serial>.
5. Skip on Windows. Detect early and route to avdmanager + Studio.
6. Prefer google_apis over aosp unless the user specifically needs a Google-services-free environment — most app code expects Play services to be present.

Anti-patterns

• ❌ Running android run --apks=… immediately after emulator start without waiting for sys.boot_completed=1. The install fires before package manager is ready and either fails or hangs.
• ❌ Installing x86_64 system images on Apple Silicon "for compatibility". They run translated and are dramatically slower than native arm64-v8a.
• ❌ Using google_apis_playstore for unsigned debug builds — sideloading is restricted on Play Store images.
• ❌ Trying android emulator on Windows. Known issue, will fail.
• ❌ Calling android emulator stop <avd-name> (the AVD name) instead of <serial> — silent no-op.
• ❌ Skipping --list-profiles and hardcoding a profile name that the user's CLI version doesn't ship.

Error recovery

Error	Cause	Fix
No system image found for ABI	Image not installed	android sdk list 'system-images/' then android sdk install
Emulator failed to launch	Hypervisor (HAXM/Hyper-V) misconfigured	Check emulator -accel-check from raw SDK; surface to user — outside this skill's scope
adb wait-for-device hangs > 60s	Emulator stuck on boot animation	Stop the emulator, recreate AVD; consider lower API level
cannot find avd <name>	AVD with that name doesn't exist	android emulator list, use the actual name
Out of disk space mid-boot	Default disk too small	Stop, delete AVD, recreate with bigger profile (pixel_8 etc.)