> ## Documentation Index
> Fetch the complete documentation index at: https://docs.modaal.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Set Up the Android Toolchain

> What Modaal's install-the-Android-SDK banner means and what its button installs: the pinned SDK components, a user-local JDK, and your first emulator.

<Info>
  Building the Android half of a [Duet](/duet) project needs the **[Android SDK](https://developer.android.com/tools)** and a **[JDK](https://adoptium.net/)** on your Mac, alongside Xcode. Modaal checks for both and, when something is missing, shows an **Action needed: install the Android SDK** banner with a button that installs it. This guide explains what the banner means, what the button installs, and how to verify the result. [What Claude Code alone cannot do on Android](https://modaal.dev/build-android-apps-with-claude-code) is on modaal.dev.
</Info>

## Before you start

<CardGroup cols={2}>
  <Card title="A Mac with Xcode set up" icon="apple">
    The Android toolchain installs alongside your iOS setup — [Set up Xcode](/guides/setup-xcode) first if you haven't.
  </Card>

  <Card title="Disk space for the toolchain" icon="hard-drive">
    The SDK components, the emulator system image and the JDK are a multi-gigabyte download. The setup prints the exact total it downloaded in its final receipt.
  </Card>

  <Card title="No admin password, no Homebrew" icon="lock-open">
    Everything installs user-local, under your home folder. Nothing asks for elevation and nothing touches a system package manager.
  </Card>

  <Card title="Android Studio users keep their SDK" icon="circle-check">
    If a SDK is already on the machine, the setup respects it and adds only the components that are missing.
  </Card>
</CardGroup>

***

## What the banner means

On a project with Android in scope, Modaal probes for the toolchain — the SDK components, the JDK, and an emulator. When any of them is missing, the workspace shows the **Action needed: install the Android SDK** banner with an **Install** button and the list of what is missing.

## What the button installs

The button opens **Terminal** and runs Modaal's setup there, in a window you own — Google's SDK licenses have to be accepted by you, and that happens in this window, not silently in the background. As of September 2026 the setup installs:

| Component                       | Version                        |
| ------------------------------- | ------------------------------ |
| Android platform                | android-36                     |
| Build tools                     | 36.0.0                         |
| Platform tools (includes `adb`) | current                        |
| Emulator                        | current                        |
| System image                    | android-36, Google APIs, arm64 |
| Command-line tools              | 23.0                           |
| JDK                             | Temurin 25                     |

It also creates your first emulator — a **Pixel 8 on API 36**, named `Modaal_Pixel_8_API_36` — and pre-warms the Kotlin build toolchain the project compiles with (about a minute, \~440 MB), so the first real build doesn't pay that cost.

At the end, the setup offers to add the SDK and JDK environment exports to your shell profile, so your own terminal sees the same toolchain Modaal uses. You can decline — Modaal doesn't need it.

## Where everything lives

* **The SDK** goes to `~/Library/Android/sdk` — unless the machine already points at an SDK through the standard `ANDROID_SDK_ROOT` or `ANDROID_HOME` variables, in which case that location is used and only missing components are added.
* **The JDK** goes to `~/Library/Java/JavaVirtualMachines`, the user-local directory macOS resolves JDKs from — no admin password involved.

The setup's final receipt lists every location, every component it installed or found already present, and the total it downloaded.

## Verify it worked

Modaal picks the result up without a restart: the banner clears on the next prerequisites check, and the **Run picker** offers the new emulator alongside your iOS simulators. Ask Modaal to run the app on Android and it boots the emulator and launches your app there.

## What the banner can show

| State                                         | What it means                                                                                                                              | What to do                                                     |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- |
| **Action needed**, with an **Install** button | Components are missing, and one setup run installs them. The banner lists which.                                                           | Press the button and follow the Terminal window.               |
| **Installing**                                | The setup is running in Terminal.                                                                                                          | Answer the license prompt there and let it finish.             |
| No banner                                     | The toolchain is complete.                                                                                                                 | Nothing — pick an Android device in the Run picker.            |
| An error, with no button                      | Something the setup cannot heal — for example, a custom SDK or JDK override pointing at a broken location. The banner names what is wrong. | Fix or remove the override it names, then let Modaal re-check. |

***

## Common questions

<AccordionGroup>
  <Accordion title="I already have Android Studio — will this fight my setup?" icon="circle-check">
    No. The setup respects an existing SDK found through `ANDROID_SDK_ROOT` or `ANDROID_HOME`, installs only missing components into it, and never removes anything. Your Android Studio projects keep working unchanged.
  </Accordion>

  <Accordion title="The setup stopped at the license prompt" icon="file-signature">
    Google's SDK licenses must be accepted before components can install, and declining ends the run without installing them. Run the setup again from the banner's button and answer **y** at the license prompt.
  </Accordion>

  <Accordion title="Something failed mid-run — is it safe to re-run?" icon="rotate-right">
    Yes. Re-running is the repair path: every step checks what is already in place before acting, so a second run finishes what the first one couldn't and changes nothing that succeeded.
  </Accordion>

  <Accordion title="Do I need this for an iPhone-only project?" icon="mobile-screen">
    No. The Swift-flavor Duet template and the iOS-only templates build with Xcode alone — see [the two Duet templates](/articles/duet#the-two-duet-templates). The banner appears only when a project has Android in scope.
  </Accordion>

  <Accordion title="Do the Duet tutorials need this toolchain?" icon="graduation-cap">
    From [Tutorial 2](/tutorials/duet-02-two-apps#build-the-compose-app) onward, yes: that page builds the Compose app, and every later page runs it. [Tutorial 1](/tutorials/duet-01-first-feature) needs a JDK only. The [series index](/tutorials/duet#what-do-you-need-installed) lists every prerequisite with the tutorial that first needs it.
  </Accordion>
</AccordionGroup>

Toolchain in place? [Start your first project](/guides/quickstart) and pick a Multiplatform card. What shipping an Android app involves beyond the build — the Play Console, signing keys, release tracks — is covered in [how to build an Android app](https://modaal.dev/blog/how-to-build-an-android-app).

<Note>
  **Still stuck?** Join our [community on Discord](https://discord.gg/KyQzDXxgU3) — we're happy to help you get set up.
</Note>