Android Debug Bridge (ADB) – Ultimate Developer Guide (2025)

ADB is one of those tools I use so often that I sometimes forget how intimidating it looked the first time I opened a terminal and stared at adb devices returning nothing. Over the years it’s become second nature — the bridge between “code on my machine” and “actual behavior on actual hardware.” This guide is the one I wish I’d had starting out: a complete, practical walkthrough of ADB in 2025, from installation to advanced debugging and security workflows.

What Is ADB?

Android Debug Bridge (ADB) is a command-line tool included in the Android SDK Platform Tools that lets you communicate with an Android device (physical or emulated) from a development machine. It’s the backbone of Android app development workflows — installing APKs, viewing logs, debugging, transferring files, and much more.

ADB Architecture

ADB isn’t a single monolithic program; it’s a client-server system with three components.

flowchart LR
    A[ADB Client<br/>your terminal command] --> B[ADB Server<br/>background process on your PC, port 5037]
    B --> C[ADB Daemon adbd<br/>running on the Android device]
    C --> D[Android OS / Apps]

• ADB Client: the command you type (adb shell, adb install, etc.) runs on your development machine.
• ADB Server: a background process on your development machine that manages communication with all connected devices, listening on TCP port 5037.
• ADB Daemon (adbd): runs on the Android device itself (or emulator) and executes the commands sent from the server.

When you run any adb command, the client checks if the server is running; if not, it starts one automatically, which then discovers and connects to available devices over USB or TCP/IP.

Installation and Setup

# macOS (via Homebrew)
brew install --cask android-platform-tools

# Windows (via Chocolatey)
choco install adb

# Linux (Debian/Ubuntu)
sudo apt install android-sdk-platform-tools

# Verify installation
adb version

Enabling Developer Options and USB Debugging

1. Go to Settings → About Phone.
2. Tap Build Number seven times until “You are now a developer!” appears.
3. Go back to Settings → System → Developer Options.
4. Enable USB Debugging.
5. Connect the device via USB and accept the RSA key fingerprint prompt that appears on-screen.

adb devices
# List of devices attached
# ABC123XYZ    device

Core ADB Commands Every Developer Should Know

Device and Connection Management

adb devices                  # List connected devices
adb devices -l                # List devices with additional details (model, product)
adb connect 192.168.1.50:5555 # Connect over Wi-Fi (device must have TCP/IP mode enabled)
adb tcpip 5555                 # Switch a USB-connected device to TCP/IP mode on port 5555
adb disconnect                 # Disconnect all TCP/IP devices
adb -s ABC123XYZ shell         # Target a specific device when multiple are connected
adb kill-server                # Restart the ADB server (useful when connections misbehave)
adb start-server

App Installation and Management

adb install app-release.apk               # Install an APK
adb install -r app-release.apk            # Reinstall, keeping data
adb install -d app-release.apk            # Allow downgrade (debug builds)
adb uninstall com.example.myapp           # Uninstall an app
adb shell pm list packages                # List all installed packages
adb shell pm clear com.example.myapp      # Clear app data/cache
adb shell am start -n com.example.myapp/.MainActivity  # Launch a specific activity
adb shell am force-stop com.example.myapp # Force-stop an app

File Transfer

adb push local_file.txt /sdcard/Download/   # Copy from PC to device
adb pull /sdcard/Download/file.txt ./       # Copy from device to PC
adb pull /sdcard/DCIM/Camera/ ./backup/     # Pull an entire directory

Logging and Debugging

adb logcat                          # Stream full system logs
adb logcat *:E                      # Show only Error-level logs
adb logcat -s "MyAppTag"            # Filter by a specific log tag
adb logcat -c                       # Clear the log buffer
adb bugreport ./bugreport.zip       # Generate a full bug report (logs, dumpsys, system state)

Shell Access and System Interaction

adb shell                    # Open an interactive shell on the device
adb shell getprop            # List all system properties
adb shell getprop ro.build.version.release   # Get Android version
adb shell input keyevent 26  # Simulate the power button
adb shell input text "hello" # Simulate typing text
adb shell screencap -p /sdcard/screen.png   # Take a screenshot
adb shell screenrecord /sdcard/demo.mp4     # Record the screen (Ctrl+C to stop)
adb shell wm size            # Get/set screen resolution
adb shell dumpsys battery    # Battery stats and diagnostics
adb shell dumpsys activity   # Activity stack information

Advanced Debugging Workflows

Port Forwarding for Local Development

A very common workflow when developing against a local backend server:

# Forward device port 8080 to your PC's port 8080
adb forward tcp:8080 tcp:8080

# Reverse: let the device access a server running on your PC via localhost
adb reverse tcp:3000 tcp:3000

This reverse command is especially useful for React Native or web-view-based development, where the device needs to reach localhost:3000 on your development machine as if it were running locally on the device itself.

Wireless Debugging (Android 11+)

Modern Android versions support wireless ADB debugging without an initial USB connection, using a pairing code:

# On the device: Developer Options -> Wireless debugging -> Pair device with pairing code
adb pair 192.168.1.50:37251
# Enter the 6-digit pairing code shown on the device

adb connect 192.168.1.50:41235
adb devices

Debugging ANRs and Crashes

# Pull ANR (Application Not Responding) traces
adb pull /data/anr/traces.txt

# Monitor memory usage of a specific app
adb shell dumpsys meminfo com.example.myapp

# Monitor CPU usage
adb shell top -m 10

ADB Command Reference Table

Security Considerations When Using ADB

ADB is a powerful capability, and that power cuts both ways — it’s essential for legitimate development but also a favorite tool for device tampering and, when misconfigured, a genuine attack surface.

• Never leave USB debugging permanently enabled on daily-use or production devices; it expands the local attack surface if the device is lost, stolen, or accessed by an untrusted party with physical access.
• Never enable ADB over TCP/IP on an untrusted network without authentication — an open ADB port on a device connected to a hostile network can allow unauthorized shell access, since default ADB TCP mode does not require a password beyond the initial RSA key pairing.
• Revoke USB debugging authorizations periodically (Developer Options → Revoke USB Debugging Authorizations) to remove trust from old or unknown computers.
• Be aware that malware scanning families exist that specifically scan for open ADB ports (5555) on the internet, targeting misconfigured devices (particularly some Android TV boxes and IoT devices) that ship with ADB debugging enabled by default — a known real-world exploitation pattern (e.g., botnets like ADB.Miner).

flowchart TD
    A[Device with ADB over TCP/IP enabled] --> B{Exposed to Untrusted Network?}
    B -->|Yes, port 5555 reachable| C[Attacker Scans for Open ADB Ports]
    C --> D[Unauthorized adb connect]
    D --> E[Shell Access / Malware Installation]
    B -->|No, USB only or firewalled| F[Low Risk — Standard Dev Workflow]

Comparing ADB to Other Debugging Approaches

Scripting ADB for Automated Testing Workflows

Beyond interactive debugging, ADB is frequently scripted into CI/CD pipelines for automated testing, especially for teams running instrumented UI tests across multiple device configurations. A typical automated test runner script might combine several of the commands covered above:

#!/usr/bin/env bash
# ci_test_runner.sh — Example automated test flow using ADB

set -e

APK_PATH="app-debug.apk"
TEST_APK_PATH="app-debug-androidTest.apk"
PACKAGE="com.example.myapp"
TEST_RUNNER="androidx.test.runner.AndroidJUnitRunner"

echo "[*] Waiting for device..."
adb wait-for-device

echo "[*] Installing app and test APK..."
adb install -r "$APK_PATH"
adb install -r "$TEST_APK_PATH"

echo "[*] Clearing previous app state..."
adb shell pm clear "$PACKAGE"

echo "[*] Running instrumented tests..."
adb shell am instrument -w "$PACKAGE.test/$TEST_RUNNER" | tee test_results.log

echo "[*] Pulling screenshots and artifacts..."
adb pull /sdcard/screenshots ./ci_artifacts/screenshots

echo "[*] Uninstalling test build..."
adb uninstall "$PACKAGE"

echo "[+] Test run complete."

This pattern — install, clear state, run instrumented tests, pull artifacts, clean up — forms the backbone of most Android CI pipelines, whether running against physical device farms, cloud-based device labs, or emulator instances spun up fresh for each build. Tools like Firebase Test Lab and AWS Device Farm essentially wrap this same ADB-driven workflow at scale across many device/OS combinations simultaneously, which is worth understanding even if you’re using a managed service, since debugging a failed cloud test run often comes back to inspecting the same adb logcat and dumpsys output described earlier in this guide.

Common Mistakes

• Forgetting to run adb kill-server && adb start-server when a device shows as “unauthorized” or “offline” indefinitely.
• Leaving adb tcpip mode enabled on a device that later joins an untrusted network.
• Using adb install -r on production builds without realizing it preserves potentially stale app data.
• Not filtering logcat output, leading to an unmanageable firehose of irrelevant log lines during debugging.
• Assuming ADB access implies root access — many commands (like reading other apps’ private data) still require root or a rooted device.

Troubleshooting Common ADB Connection Issues

Even experienced developers hit connection snags regularly, so it’s worth keeping a mental checklist handy: confirm the correct USB cable (some cables are charge-only and lack data lines), try a different USB port or cable if the device isn’t detected, ensure the correct OEM USB drivers are installed on Windows, and double-check that the device screen is unlocked when the authorization prompt should appear, since some manufacturers suppress the dialog on a locked screen. If adb devices lists a device as offline, a full adb kill-server followed by adb start-server resolves the issue more often than any other single fix, since it forces a clean renegotiation between the client, server, and daemon.

FAQs

Do I need root access to use ADB? No, most ADB functionality (installing apps, logging, shell access to your own app’s sandbox, file transfer to public storage) works without root. Root unlocks additional capabilities like accessing other apps’ private data directories.

Can ADB work without a USB cable? Yes — modern Android (11+) supports wireless debugging via a pairing code, and any Android version supports switching to adb tcpip mode after an initial USB connection.

Why does my device show as “unauthorized”? This typically means the RSA key confirmation dialog on the device hasn’t been accepted yet, or a previous authorization was revoked. Reconnect the cable and check the device screen for the prompt.

Is it safe to leave ADB over Wi-Fi enabled permanently? Not recommended — it increases attack surface, especially on networks you don’t fully control. Disable wireless debugging when not actively developing.

What’s the difference between ADB and Fastboot? ADB communicates with a fully booted Android OS for app and system interaction; Fastboot communicates with the device’s bootloader for flashing partitions, recovery images, and firmware, and only works when the device is in bootloader/fastboot mode.

Summary and Recommendations

ADB remains, in 2025, the essential bridge between your development machine and real Android devices — indispensable for installing builds, chasing down bugs through logcat, transferring files, and scripting device automation. Learning its core commands thoroughly pays off constantly during development, but treat it with the same security discipline you’d apply to any privileged remote access tool: disable it when not in use, never expose it to untrusted networks, and periodically audit which machines are authorized to connect to your devices.

Further Reading and References

• Android Developers: ADB Official Documentation
• Android Developers: Wireless Debugging
• OWASP Mobile Application Security Testing Guide
• Android Open Source Project (AOSP) Documentation