Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Flutter and app store releases

The Android Emulator does not start, or crashes, on a Mac

ErrorThe emulator window never opens, or closes right after launch

Short answer

On a Mac the emulator fails to start for three documented reasons: less than 5 GB of free disk space, a system image built for the wrong CPU architecture, or a graphics mode that does not work on your machine. Check the disk first, then confirm the image matches your chip, then switch the AVD to software graphics.

  • Applies to Android Emulator, Android Studio, macOS on Apple silicon and Intel
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask the emulator itself whether a hypervisor is usable, then check free disk space. Both take a few seconds and rule out the two most common causes.

    ~/Library/Android/sdk/emulator/emulator -accel-check
    df -h ~
  2. 2Match what you see, then jump to its fix

    1. 1The emulator exits at start and df shows a nearly full diskLess than 5 GB of free disk spaceFix
    2. 2The emulator runs very slowly or reports no VM accelerationThe system image does not match your Mac's chipFix
    3. 3Shader compilation failures, glitches or crashes only with hardware renderingHardware graphics crash on Apple silicon (MoltenVK)Fix

What does the error look like?

  • The emulator window never opens, or closes right after launch
  • Black or glitching screen, or a crash with hardware graphics
  • Emulator is slow and does not use VM acceleration

Cause 1 of 3

Less than 5 GB of free disk space

1Check

The Android docs say the emulator checks free disk space on startup and does not start unless at least 5 GB is free.

df -h ~

2Fix

Free space on the volume that holds your home folder and the AVD files, then start the AVD again.

du -sh ~/.android/avd ~/Library/Android/sdk

3Verify

At least 5 GB shows as available, and the AVD boots.

df -h ~

Confirmed by developer.android.com

Did this fix it?

Cause 2 of 3

The system image does not match your Mac's chip

1Check

The docs list the pairs that can use VM acceleration: x86 or x86_64 images on x86_64 CPUs and arm64-v8a images on ARM64. Images that do not follow this cannot use VM acceleration. Apple silicon is a supported ARM64 processor.

uname -m
grep -E "abi.type|image.sysdir" ~/.android/avd/*.avd/config.ini

2Fix

Create a new AVD in Device Manager with a system image that matches the output of uname -m: arm64-v8a on arm64, x86_64 on an Intel Mac. Delete the old AVD.

~/Library/Android/sdk/emulator/emulator -list-avds

3Verify

-accel-check reports Hypervisor.Framework and the new AVD boots quickly.

~/Library/Android/sdk/emulator/emulator -accel-check

Confirmed by developer.android.com

Did this fix it?

Cause 3 of 3

Hardware graphics crash on Apple silicon (MoltenVK)

1Check

The docs say that on Apple silicon the emulator uses MoltenVK for Vulkan in hardware mode, and MoltenVK does not support every Vulkan feature.

grep hw.gpu.mode ~/.android/avd/*.avd/config.ini

2Fix

Run the AVD with software rendering, or turn off only Vulkan to keep hardware acceleration for GLES. You can also set Graphics acceleration to Software in the AVD's Additional Settings.

~/Library/Android/sdk/emulator/emulator -avd my_avd -gpu swiftshader
~/Library/Android/sdk/emulator/emulator -avd my_avd -feature -Vulkan

3Verify

The device boots to the home screen and the app renders correctly.

~/Library/Android/sdk/emulator/emulator -avd my_avd -gpu swiftshader

Confirmed by developer.android.com

Did this fix it?

How do I stop it coming back?

  • Keep at least 5 GB free; large AVD snapshots add up.
  • Create AVDs whose system image architecture matches the Mac they run on.
  • Keep the Android Emulator updated in SDK Manager.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Mobile apps

Android Studio cannot pair the phone over Wi-Fi

The Pair devices over Wi-Fi dialog lists no device

Wireless pairing needs the phone on Android 11 or higher and on the same Wi-Fi network as the computer, with current Platform-Tools.

4 causes, each with a fix

Mobile apps

adb tcpip 5555 fails because no device is found

adb: more than one device/emulator

adb tcpip only works while the device is attached and listed by adb, because it tells the phone to start listening on port 5555.

4 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.