Update/Add Android SDK Command-line Tools

[jpcottin]

Tool name

Android SDK Command-line Tools (cmdline-tools)

Tool license

Android Software Development Kit License Agreement (already shipped in the image today)

Add or update?

• Add
• Update

Desired version

22.0 (cmdline-tools;latest)

Approximate size

173 MB (Linux), 149 MB (macOS), 148 MB (Windows)

Brief description of tool

The Android SDK Command-line Tools preinstalled on the runner image are at 12.0, while the
current release is 22.0.

• Image contents: https://raw.githubusercontent.com/actions/runner-images/main/images/ubuntu/Ubuntu2404-Readme.md
  lists Android Command Line Tools | 12.0
• Current release: cmdline-tools;latest resolves to revision 22.0 on the stable channel in
  https://dl.google.com/android/repository/repository2-1.xml

This is not only a "please bump a version" request: the 12.0 tools silently mis-handle the newer
Major.Minor package versions, which produces broken emulator runs with no error message
pointing at the SDK tools.

Which images are affected

The parsing fix landed in cmdline-tools 20.0. Every image except ubuntu-26.04 ships an older
version, so all of them write a broken AVD target for Major.Minor packages:

Runner image	Android Command Line Tools	Major.Minor packages
ubuntu-22.04	9.0	broken experience with latest images like 37.0
ubuntu-24.04	12.0	broken
ubuntu-26.04	20.0	ok (but see below — still worth updating)
macos-14, macos-14-arm64	11.0	broken
macos-15, macos-15-arm64	16.0	broken
macos-26, macos-26-arm64	16.0	broken
windows-2022	8.0	broken
windows-2025	16.0	broken
windows-2025 (VS2026)	19.0	broken

(The arm64 Ubuntu and Windows images do not list an Android SDK.)

Measured by running each cmdline-tools release against the same package and reading the target=
line it wrote into the AVD's .ini:

cmdline-tools	target= written
8.0, 9.0, 11.0, 12.0, 16.0, 19.0	android-0 ❌
20.0, 22.0	android-37.0 ✅

Why it matters

Android now publishes platforms and system images with minor versions — android-37.0,
android-37.1, e.g. system-images;android-37.0;google_apis_ps16k;x86_64. The 12.0 tools predate
that scheme:

avdmanager create avd --package 'system-images;android-37.0;...' succeeds
but writes an invalid target into the AVD's .ini:

target=android-0

The emulator will see this as a very old system image and that means the
Vulkan / GLDirectMem auto-enable is skipped, and the emulator renders incorrectly — blank or
corrupted frames — while every command in the workflow still reports success. Nothing in the
failure points back at the SDK tools, so this costs a lot of debugging time.

Current workaround, and why it is awkward

Workflows have to update the tools themselves before calling avdmanager, and sdkmanager refuses
to overwrite the preinstalled directory:

Package "Android SDK Command-line Tools (latest)" (cmdline-tools;latest) should be installed in
"/usr/local/lib/android/sdk/cmdline-tools/latest" but it already exists.
Installing in "/usr/local/lib/android/sdk/cmdline-tools/latest-2" instead.

so every job needs:

yes | "$SDK/cmdline-tools/latest/bin/sdkmanager" --install "cmdline-tools;latest" > /dev/null
if [ -d "$SDK/cmdline-tools/latest-2" ]; then
  rm -rf "$SDK/cmdline-tools/latest"
  mv "$SDK/cmdline-tools/latest-2" "$SDK/cmdline-tools/latest"
fi

Without the rm/mv, the update lands beside the old copy and avdmanager still resolves to 12.0.

Worth noting

The same image ships Android SDK Platform-Tools 37.0.0, which is current. So the image is not
generally stale — it is specifically the component that parses package paths and writes AVD targets
that lags, which is why this is easy to miss.

sdkmanager is deprecated soon, and 22.0 ships its replacement

sdkmanager now announces its own deprecation on every invocation, and points at the Android CLI:

WARNING: The SDK Manager CLI tool (sdkmanager) is deprecated. Use Android CLI instead.
The 'android' binary can also be found in the cmdline-tools directory, and 'android sdk' is the
replacement for 'sdkmanager'.
To learn more about the Android CLI and how to use it, see the documentation
(https://d.android.com/tools/agents/android-cli)

This is not a one-off: the widely used reactivecircus/android-emulator-runner action shells out to
sdkmanager several times per run (licenses, build-tools/platform-tools/platform, emulator, system
images), so this warning is repeated four or more times in the logs of essentially every Android
workflow on GitHub-hosted runners.

The important detail is in that message: the android binary lives inside cmdline-tools
itself. So this does not require packaging a new tool:

• cmdline-tools 22.0 ships cmdline-tools/latest/bin/android (version 1.0.15857036)
• cmdline-tools 20.0 does not contain an android binary

Updating the preinstalled cmdline-tools to 22.0 therefore delivers both fixes in a single version
bump: avdmanager parses Major.Minor packages correctly, and the Android CLI becomes available
to workflows out of the box:

android sdk list
android sdk install system-images/android-37.0/google_apis_ps16k/x86_64
android emulator create <profile>

Request

1. Update the preinstalled cmdline-tools to latest (22.0) on every image that ships the Android
SDK. This is the core fix, and one bump addresses everything above:

• avdmanager stops silently writing target=android-0 for Major.Minor packages (needs >= 20.0)
• the Android CLI ships along with it, since the android binary lives in cmdline-tools (needs 22.0)

This applies to ubuntu-26.04 too: at 20.0 it parses correctly, but it is still on the deprecated
tooling and does not ship the android binary.

2. Alternatively (or additionally), install the Android CLI explicitly. It has its own installer,
independent of cmdline-tools, which may fit the image build better and lets the CLI be updated on
its own cadence rather than being pinned to whatever cmdline-tools revision is installed:

# Linux
curl -fsSL https://dl.google.com/android/cli/latest/linux_x86_64/install.sh | bash

# macOS (Apple silicon)
curl -fsSL https://dl.google.com/android/cli/latest/darwin_arm64/install.sh | bash

# macOS (Intel)
curl -fsSL https://dl.google.com/android/cli/latest/darwin_x86_64/install.sh | bash

:: Windows
curl -fsSL https://dl.google.com/android/cli/latest/windows_x86_64/install.cmd -o "%TEMP%\i.cmd" && "%TEMP%\i.cmd"

Documentation: https://d.android.com/tools/agents/android-cli

Doing both would be ideal: the cmdline-tools bump repairs the existing avdmanager behaviour that
workflows depend on today, while an explicitly installed android CLI gives a supported path forward
as sdkmanager/avdmanager are wound down.

URL for tool's homepage

https://developer.android.com/tools/agents/android-cli/release-notes

Provide a basic test case to validate the tool's functionality.

# Validates that the preinstalled command-line tools handle a Major.Minor
# system image package (android-37.0) correctly.
# NB: no `pipefail` -- `yes | sdkmanager` exits 141 (SIGPIPE) under it, because
# sdkmanager stops reading before `yes` is done.
set -eu

SDK="${ANDROID_HOME:-${ANDROID_SDK_ROOT:-/usr/local/lib/android/sdk}}"
CLT="$SDK/cmdline-tools/latest/bin"
PKG='system-images;android-37.0;google_apis_ps16k;x86_64'

# 1. Version must be >= 20.0 for correct parsing, >= 22.0 to also ship the Android CLI.
"$CLT/sdkmanager" --version

# 2. From 22.0 the Android CLI is bundled; this should print a version, not "not found".
"$CLT/android" --version

# 3. Create an AVD from a Major.Minor system image package.
yes | "$CLT/sdkmanager" --install "$PKG" > /dev/null
echo no | "$CLT/avdmanager" create avd --force -n majorminor-test \
    --package "$PKG" --abi 'google_apis/x86_64' --device pixel_6

# 4. The AVD must record the real platform, not android-0.
TARGET=$(grep '^target=' "${ANDROID_AVD_HOME:-$HOME/.android/avd}/majorminor-test.ini")
echo "$TARGET"
"$CLT/avdmanager" delete avd -n majorminor-test > /dev/null 2>&1 || true

# PASS: target=android-37.0
# FAIL: target=android-0   <- what cmdline-tools < 20.0 writes, silently
[ "$TARGET" = "target=android-37.0" ]

Platforms where you need the tool

• Azure DevOps
• GitHub Actions

Runner images where you need the tool

• Ubuntu 22.04
• Ubuntu 22.04 Arm64
• Ubuntu 24.04
• Ubuntu 24.04 Arm64
• Ubuntu 26.04
• Ubuntu 26.04 Arm64
• Ubuntu Slim
• macOS 14
• macOS 14 Arm64
• macOS 15
• macOS 15 Arm64
• macOS 26
• macOS 26 Arm64
• Windows Server 2022
• Windows Server 2025
• Windows Server 2025 with Visual Studio 2026
• Windows Desktop 11
• Windows Desktop 11 with Visual Studio 2026

Can this tool be installed during the build?

# I wouldn't recommend installing during the build as it would be best to update before the build.
# Here are the options to install "during the build"
# Option A (not great): update cmdline-tools in the job.
SDK="${ANDROID_HOME:-${ANDROID_SDK_ROOT:-/usr/local/lib/android/sdk}}"
yes | "$SDK/cmdline-tools/latest/bin/sdkmanager" --install "cmdline-tools;latest" > /dev/null

# BUT sdkmanager refuses to overwrite the preinstalled directory and installs beside
# it as "latest-2"; without this move, avdmanager still resolves to the old copy.
if [ -d "$SDK/cmdline-tools/latest-2" ]; then
  rm -rf "$SDK/cmdline-tools/latest"
  mv "$SDK/cmdline-tools/latest-2" "$SDK/cmdline-tools/latest"
fi
"$SDK/cmdline-tools/latest/bin/avdmanager" list device > /dev/null

# Option B: install the Android CLI instead (independent of cmdline-tools).
curl -fsSL https://dl.google.com/android/cli/latest/linux_x86_64/install.sh | bash
echo "$HOME/.local/bin" >> "$GITHUB_PATH"

Tool installation time in runtime

5 seconds

Are you willing to submit a PR?

No response

[v-SergeiRadich]

Hi!

We will check and discuss it internally.