Setting ANDROID_HOME Environment Variable on macOS

Overview

When developing Android applications on macOS, many build tools—including Gradle, command-line SDK tools, and CI systems—depend on the ANDROID_HOME (or the newer ANDROID_SDK_ROOT) environment variable to locate the Android SDK installation. Properly configuring these variables ensures that command-line builds, IDE integrations, and automated scripts can locate the SDK without errors.

This guide explains how to set up the Android SDK environment variables on macOS, covering common shells (zsh and bash) and terminal usage.

Prerequisites

Before setting environment variables, ensure that:

1. Android Studio is installed
2. The Android SDK is installed via Android Studio
3. You know the SDK installation path (default location is under your user directory)

By default, Android Studio installs the SDK in:

~/Library/Android/sdk

If you customized the location, substitute your actual path in all steps below.

Identify Your Shell

macOS defaults to zsh as of Catalina and later (10.15+). Older systems may use bash.

To determine your current shell, run:

echo $SHELL

This outputs a path containing either zsh or bash, indicating your shell.

Setting Environment Variables for zsh (Default)

If using zsh, update the ~/.zshrc file.

Open ~/.zshrc

nano ~/.zshrc

Add Environment Variables

Append the following lines (adjust SDK path if needed):

# Android SDK path
export ANDROID_SDK_ROOT="$HOME/Library/Android/sdk"
export ANDROID_HOME="$ANDROID_SDK_ROOT"

# Tools and platform tools
export PATH="$ANDROID_SDK_ROOT/emulator:$PATH"
export PATH="$ANDROID_SDK_ROOT/platform-tools:$PATH"
export PATH="$ANDROID_SDK_ROOT/tools:$PATH"
export PATH="$ANDROID_SDK_ROOT/tools/bin:$PATH"

Save and Apply

After adding the lines:

source ~/.zshrc

This reloads the configuration and applies the variables in the current terminal session.

Setting Environment Variables for bash

If your shell is bash, update the ~/.bash_profile or ~/.bashrc file.

Open ~/.bash_profile

nano ~/.bash_profile

Add Environment Variables

Add:

export ANDROID_SDK_ROOT="$HOME/Library/Android/sdk"
export ANDROID_HOME="$ANDROID_SDK_ROOT"

export PATH="$ANDROID_SDK_ROOT/emulator:$PATH"
export PATH="$ANDROID_SDK_ROOT/platform-tools:$PATH"
export PATH="$ANDROID_SDK_ROOT/tools:$PATH"
export PATH="$ANDROID_SDK_ROOT/tools/bin:$PATH"

Save and Apply

source ~/.bash_profile

This loads the new variable definitions for the current session.

Verify Your Configuration

To confirm that environment variables are set correctly, run:

echo $ANDROID_HOME
echo $ANDROID_SDK_ROOT

Both commands should return your SDK path (for example /Users/yourname/Library/Android/sdk).

To test that the tools are available, run:

adb --version
sdkmanager --list

If these commands return version information without errors, your environment setup is correct.

Notes and Best Practices

Use ANDROID_SDK_ROOT

Modern SDK tools (including command-line build systems) primarily reference ANDROID_SDK_ROOT rather than ANDROID_HOME. The latter is still widely used for backward compatibility. Setting both to the same value reduces friction across tooling.

Avoid Duplicate Entries

Ensure that PATH doesn’t include duplicate entries for SDK tools. Redundant paths can cause inconsistencies and increase build times.

IDE and CLI Alignment

Android Studio reads environment variables from the shell process that launches it. If the IDE was opened before setting the environment variables, restart Android Studio after applying variable changes.

Troubleshooting

“Command not found” errors

If commands like adb or sdkmanager are not found:

• Confirm that platform-tools and tools/bin folders exist under your SDK path
• Confirm that the correct SDK path is exported in your shell file
• Run source ~/.zshrc or source ~/.bash_profile to reload

Multiple SDK Installations

If you have multiple SDK locations (for example one installed via Android Studio and another manually), ensure that only the intended SDK path is exported.