Guide

Everything about running Android apps on your Mac with Mac Android Subsystem.

Getting started

Mac Android Subsystem runs Android apps on your Mac as if they were Mac apps. Android runs in a small virtual machine you never see; each Android app appears as its own Mac app, with its own window, Dock icon and place in Launchpad.

  1. Download the DMG, open it and drag Mac Android Subsystem to Applications.
  2. Open it. The setup window downloads Android (about 1.5 GB) and prepares it.
  3. Optionally tick Install F-Droid (an open-source app store) and Always ready.
  4. Afterwards the Subsystem lives in the menu bar. Its icon shows whether Android is off, starting or running.

You need a Mac with Apple silicon (M1 or later) and macOS 15 or later. Android uses up to a quarter of your memory by default (at most 6 GB) and about 8 GB of disk.

The Android image

The Subsystem downloads LineageOS 24 (Android 17) built for LineageOS's virtio_arm64only virtual-machine target. It contains no Google apps, which keeps it small and means no Google account is needed. This project's build changes one thing: Android doesn't ask "Allow USB debugging?", because nobody sees Android's own screen and ADB only listens on 127.0.0.1.

The image itself is never modified. Your apps and data live in separate copy-on-write disks, so Reset Android is instant and a new image never needs re-downloading anything else.

Settings › Advanced › Use an Image File accepts any LineageOS UTM-VM-lineage-…-virtio_arm64only.zip or unpacked .utm folder. If an image does ask to allow USB debugging, the Subsystem shows Android's screen once: tick Always allow from this computer and click Allow.

Installing apps

  • Double-click an .apk, .apks, .apkm or .xapk file. Android starts if needed, the app installs and opens.
  • Drag files onto Settings › Apps, or use Install Android App… in the menu bar.
  • F-Droid installs with one click from Settings › Apps. Apps you install inside Android appear on the Mac within seconds.

Installed apps appear in ~/Applications/Android Apps, so Launchpad and Spotlight find them and you can keep them in the Dock. To uninstall, right-click an app in Settings › Apps.

Apps that require Google Play services, and apps built only for Intel Android devices, won't run.

App windows

Each window is its own Android display. Resizing the window resizes the display, so apps adapt like on a tablet.

ToDo this
Tap, swipeClick, drag
ScrollTrackpad or mouse wheel
Go backThe ‹ button in the title bar, ⌘[ or Esc
Copy, paste⌘C, ⌘V (Android's clipboard syncs to the Mac automatically)
Restart a stuck appView › Restart

Settings › Advanced has an App size slider and an option to show Android's on-screen keyboard.

Always Ready

Turn on Always Ready (in the menu bar, the setup window or Settings › System) and the Subsystem starts when you log in and keeps Android running in the background. Android apps then open in about a second, as fast as Mac apps.

At login it stays quietly in the menu bar. The menu bar item offers:

  • Android's status and the current performance level
  • Start, Restart and Turn Off Android
  • The four performance modes
  • Always Ready on or off
  • Open an Android app, install one
  • Settings and Quit (quitting turns Android off cleanly)

When the last Android app closes

Settings › System decides what happens then:

SettingWhat happens
Automatic (default)Smart, Standard and Performance keep Android ready; Power Saver turns it off when the last app closes (below).
As neededAndroid turns off a few minutes after the last app closes (you choose how many).
ContinuousAndroid stays ready.

In Power Saver mode Android never runs without an app open: it turns off 30 seconds after the last Android app closes, whatever is chosen here, and Always Ready doesn't start it at login. The short wait means closing and reopening an app doesn't cost a restart.

Performance modes

Pick a mode in the menu bar or Settings › Performance. Modes apply while Android runs, without restarting it.

ModeWhat it does
Power SaverA hybrid of saving power and Smart. Android only runs while an Android app is open. While it does, it saves power by default (QEMU as a background task on the efficiency cores, two processor cores online in Android, 40% of its memory back to macOS, Android's battery saver on, 30 fps windows) and steps up to Balanced for the Android app in front when the Mac is plugged in and isn't busy.
SmartKeeps Android ready in the background and adapts every few seconds and whenever something changes: full speed for what you're using, and power saving as soon as other apps need the Mac or the battery runs low (see below).
StandardAndroid as it is, with nothing tuned: every core and all of its memory at normal priority, and Android's own power settings. Android stays ready.
PerformanceMaximum performance, all the time: every core and all of Android's memory, Android's fixed-performance mode and game mode for the game in front, a higher-quality stream and up to 120 fps on ProMotion displays. Also keeps macOS from throttling the app window.

How Smart decides

WhenLevel
Other apps are using most of the processor, memory is tight, Low Power Mode is on, the Mac is hot, or the battery is below 20%Saving power (Balanced for the Android app in front, so it stays usable)
No Android app window openSaving power (Android stays ready)
A game is in frontPerformance
Another Android app is in frontPerformance (Balanced on battery)
Android windows open, a Mac app in frontBalanced (saving power on battery)

Balanced keeps half the cores and 85% of the memory at 60 fps. Settings › Performance sets the most Android may use; changing those limits takes effect the next time Android starts.

Taking processor cores offline needs the project's own Android image (a userdebug build). With other images, the modes still change priority, memory, Android's power settings and frame rate.

Game controllers

Pair a controller in System Settings › Bluetooth, or plug it in. Any controller macOS supports works: Xbox Wireless, PlayStation DualSense and DualShock 4, Nintendo Switch Pro and MFi controllers.

When an Android app's window is in front, each controller appears inside Android as a standard gamepad (an Xbox 360-style pad, which every Android game supports). Sticks, analog triggers, the d-pad and all buttons work, for up to eight controllers. Switch to another Android window and the controller follows.

To turn this off, use Settings › Performance › Use game controllers in Android games.

Privacy

Settings › Privacy works like Privacy & Security on your Mac. It lists Camera, Microphone, Location, Contacts, Calendars, Photos & Videos, Music & Audio, Files, Notifications, Phone, Call Logs, Messages, Nearby Devices, Body Sensors and Physical Activity, with the Android apps that asked for each. Turn an app's access on or off with its switch; Android applies it right away. You can also right-click an app in Settings › Apps and choose Privacy… to see everything that one app may use.

A lock means Android itself manages that permission. Turning location on allows it while the app is in use; turning it off also removes background access.

What Android can actually reach on your Mac: the microphone only when Let Android use this Mac's microphone is on (Privacy › Microphone or Settings › System; it applies the next time Android starts). Android has no camera, location source, phone service or body sensors on a Mac yet, so apps get nothing from those even when allowed.

Storage and clean-up

Settings › Storage shows how much space the Android image, Android's apps and data, the launchers and everything else use. With Clean up automatically on (the default), the Subsystem tidies up at launch, every six hours and after Android turns off:

  • finished and abandoned downloads, leftovers from installing apps and Android images, and old Android images;
  • icons of apps you removed, old notification images, and logs over 2 MB;
  • once a day, Android trims its storage (sm fstrim), so space Android frees is given back to your Mac.

When your Mac has less than 15 GB free, it also clears Android apps' caches and, while Android is off, compacts Android's disks. Compacting also runs weekly when the Mac is plugged in. Clean Up Now does everything at once.

Developers and ADB

ADB listens on 127.0.0.1:58526, and only on your Mac. Turn on Developer mode in Settings › Advanced to see it, then:

adb connect 127.0.0.1:58526

Android Studio lists it like a device. The project's image is a userdebug build, so adb root works.

Troubleshooting

  • "Port 58526 is in use": another Android emulator or ADB tool holds the port. Quit it and start Android again.
  • A window stays on "Starting Android…": open the menu bar item to see the status. Settings › Advanced › Show Log and Show Android Console say what happened.
  • A window is black: the app may have closed itself. Use View › Restart, or close and reopen the window.
  • Apps are missing from Launchpad: Settings › Advanced › Rebuild App Launchers.
  • A controller doesn't respond: click the game's window so it's in front, and check the controller works in System Settings › Game Controllers.
  • macOS blocks the first launch: builds without a Developer ID need right-click › Open the first time.
  • To see Android's own home screen, turn on Show Android's own screen in Settings › Advanced and restart Android.

How it works

  • The Subsystem app runs QEMU with Apple's Hypervisor framework (-accel hvf), forwards ADB to 127.0.0.1:58526, and talks to Android with its own ADB client.
  • A bridge app inside Android reports installed apps, their icons and notifications.
  • Launchers in ~/Applications/Android Apps are small Mac apps, one per Android app, so each has its own Dock icon.
  • Each window starts the scrcpy server inside Android with a new virtual display for its app, decodes the H.264 stream in hardware, and sends touches, keys, scroll, clipboard and controller input back.
  • Performance modes adjust QEMU's scheduling class, a memory balloon, Android's online cores and power settings, and the stream's frame rate.

The source's docs/ARCHITECTURE.md has the full picture.

Building it yourself

On a Mac with Xcode 16 or later and Homebrew:

brew install xcodegen qemu dylibbundler
android/bridge/build.sh                 # bridge.apk (needs ANDROID_HOME and a JDK)
core/scripts/fetch-scrcpy-server.sh     # scrcpy server 5.0.1, checksum-verified
core/scripts/bundle-qemu.sh             # optional while developing
cd apple && xcodegen generate && open MacSubsystemForAndroid.xcodeproj

The Android image is built on Linux by rom/build-rom.sh (about 300 GB of disk, 32 GB of RAM, several hours) or by the Build Android image workflow on a self-hosted runner.