Complete Guide to Installing and Configuring Android Debug Bridge (ADB) on macOS

ADB Overview and Working Principles

Android Debug Bridge (ADB) is a versatile command-line tool that facilitates communication between development computers and Android devices. ADB employs a client-server architecture comprising three core components: the client sends commands and runs on the development machine; the daemon (adbd) executes commands on the device; and the server manages communication between client and daemon. This architecture enables developers to send various debugging and testing commands to connected Android devices through the command-line terminal.

Pre-installation Preparation

Before beginning ADB installation, ensure that Android devices have Developer Options and USB Debugging enabled. Navigate to device Settings, locate "About Phone," and tap "Build Number" seven times to activate Developer Mode. Return to the main Settings screen, access the newly appeared "Developer Options" menu, and enable "USB Debugging." This step is crucial for subsequent device connection and command execution.

Installing ADB Using Homebrew

Homebrew, one of the most popular package managers for macOS, offers the simplest and most automated ADB installation method. First, install the Homebrew package manager by executing the following command in Terminal:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

After installation completes, install Android platform tools using:

brew install android-platform-tools

Homebrew automatically handles dependencies and path configuration, allowing immediate use of adb commands post-installation. This method's advantage lies in its automatic update mechanism, ensuring always using the latest platform tools version.

Manual Platform Tools Installation

For users preferring manual control, directly download and configure Android platform tools. Visit the Android developer website's Platform Tools download page, select "SDK Platform-Tools for Mac" for download. After downloading, navigate to the download directory and extract files:

cd ~/Downloads/
unzip platform-tools-latest*.zip

Move extracted tools to a secure directory:

mkdir ~/.android-sdk-macosx
mv platform-tools/ ~/.android-sdk-macosx/platform-tools

Next, add platform tools to the system path. Depending on the shell type used (bash or zsh), edit the corresponding configuration file:

echo 'export PATH=$PATH:~/.android-sdk-macosx/platform-tools/' >> ~/.bash_profile
source ~/.bash_profile

For zsh users, replace ~/.bash_profile with ~/.zshrc.

Installation via SDK Manager

The third method involves complete Android SDK installation. Download command-line tools from the Android developer website, extract and move to specified directory:

cd ~/Downloads/
unzip tools_r*-macosx.zip
mkdir ~/.android-sdk-macosx
mv tools/ ~/.android-sdk-macosx/tools

Run the SDK Manager:

sh ~/.android-sdk-macosx/tools/android

In the graphical interface, deselect all other components, retaining only "Android SDK Platform-tools" option. Click "Install Packages," accept license agreements and begin installation. After installation completes, similarly add platform tools path to system environment variables.

Environment Variable Configuration and Verification

Regardless of installation method chosen, proper environment variable configuration is crucial for ensuring ADB functions correctly. Beyond basic PATH variable configuration, set ANDROID_HOME environment variable pointing to SDK installation directory. After configuration, restart Terminal or execute source command to apply changes.

The simplest method to verify successful installation involves connecting an Android device and executing:

adb devices

If installation and configuration are correct, Terminal will display connected devices list. During initial connection, device will prompt USB debugging authorization dialog requiring "Allow" click to establish trust relationship.

Basic ADB Command Usage

After installation configuration completes, begin using various ADB commands for device management and debugging. Common commands include:

adb install path_to_apk      # Install application
adb uninstall package_name   # Uninstall application
adb shell                    # Enter device shell environment
adb pull remote local        # Copy files from device
adb push local remote        # Copy files to device
adb logcat                   # View device logs

When multiple devices are connected, use -s option to specify target device serial number, or set ANDROID_SERIAL environment variable.

Wireless Debugging Configuration

Android 11 and higher versions support native wireless debugging functionality. Ensure development computer and device connect to same Wi-Fi network, enable "Wireless debugging" in device's Developer Options. Select "Pair device with pairing code," record displayed IP address, port number, and pairing code.

Execute in computer terminal:

adb pair IP_address:port_number

Enter pairing code when prompted to complete device pairing, then use:

adb connect IP_address:port_number

to establish wireless connection. This method eliminates USB connection limitations, particularly suitable for multi-device simultaneous debugging scenarios.

Troubleshooting and Common Issues

Various issues may arise during ADB usage. If devices cannot be recognized, first check whether USB debugging is enabled, USB cables function properly. Try restarting ADB server:

adb kill-server
adb start-server

For permission issues, may need to configure udev rules (on Linux systems) or check macOS USB device access permissions. For wireless connection problems, ensure network configuration permits inter-device communication, check firewall settings.

Advanced Features and Best Practices

Beyond basic debugging functionality, ADB provides numerous advanced features. Using adb forward command enables port forwarding, implementing network communication between host and device. adb shell supports direct command execution on devices, including file operations, process management, and system property modifications.

For automated testing and script writing, recommend implementing complete error handling and timeout mechanisms. Regularly update platform tools to latest versions to ensure compatibility and security. In production environments, exercise caution when using advanced commands that may impact system stability.