ADB, short for Android Debug Bridge, is a command-line toolkit that lets a computer communicate with any Android device over USB or Wi-Fi.
It grants low-level access to system services, file systems, and application runtimes, enabling developers and power users to sideload apps, capture logs, modify permissions, and automate complex workflows.
Architecture and Core Components
Client, Daemon, and Server Triad
The ADB client runs on your workstation and parses commands you type in the terminal.
The ADB daemon, adbd, lives on the Android device and listens for instructions on port 5555 by default.
A persistent background server on the host multiplexes connections, allowing multiple clients to share the same physical link.
Transport Layer Options
USB transport uses the fastboot or MTP driver stack, depending on the device state.
TCP transport swaps to port 5555 over Wi-Fi after an initial USB handshake, letting you unplug the cable and keep debugging.
Emulator transport is a Unix domain socket that loops back to the Android emulator process with zero latency.
Protocol Messages and Payloads
Every ADB packet has a 24-byte header followed by a variable-length payload.
The header encodes command type, argument count, and data length, while the payload can be shell commands, file streams, or binary APK data.
Understanding the protocol helps when you need to write custom wrappers or inspect traffic with Wireshark.
Installation Across Platforms
Windows Setup
Download the platform-tools ZIP from Google, unzip to C:Android, and add that folder to the system PATH.
Install the OEM USB driver through Device Manager to stop the dreaded “device unauthorized” prompt.
macOS Setup
Grab the same ZIP, move it to ~/Library/Android/sdk/platform-tools, and add it to ~/.zshrc.
macOS does not need extra drivers; just trust the RSA fingerprint when the dialog appears.
Linux Setup
Sudo apt install android-tools-adb on Debian-based distros or use the official SDK manager.
Create a 51-android.rules udev file to grant non-root users access to device nodes under /dev/bus/usb.
Enabling Developer Options and USB Debugging
Unlocking the Menu
Navigate to Settings > About Phone and tap Build Number seven times until you see “You are now a developer”.
Authorizing the Host Key
Plug the device into the computer, unlock the screen, and tap “Allow” on the RSA fingerprint dialog.
Check the box “Always allow from this computer” to suppress future prompts.
Verifying the Connection
Open a terminal and type adb devices to list attached devices.
A status of “device” means you are authenticated and ready to issue commands.
Essential Commands for Daily Workflows
Installing APKs
adb install myapp.apk pushes the package to /data/local/tmp and triggers the package manager.
Add the -r flag to reinstall while preserving data, or -g to auto-grant all runtime permissions.
Capturing Real-Time Logs
adb logcat -T 10:00 shows logs starting from 10 a.m. today.
Filter with adb logcat | grep “MyTag” to isolate your own application output.
Copying Files Bidirectionally
adb pull /sdcard/Download/report.csv ~/Desktop grabs a single file.
adb push backup.tar /sdcard/Backup/ uploads an entire archive to the device.
Advanced Shell Access
Interactive Shell Sessions
adb shell drops you into a minimal ash or mksh prompt, depending on the Android version.
Run su if you have root to gain unrestricted access to /system and /vendor partitions.
One-Liner Commands
adb shell am start -a android.intent.action.VIEW -d “https://example.com” launches the default browser without entering the shell.
Chain with && to run multiple commands in a single line.
Process and Memory Inspection
adb shell dumpsys meminfo com.example.app prints a detailed heap breakdown.
Use grep to find the line labeled “TOTAL” and spot memory leaks at a glance.
Port Forwarding and Network Tricks
Local Port Forwarding
adb forward tcp:8080 tcp:8080 maps a host port to the device, useful for testing localhost web servers.
Remote Port Forwarding
adb reverse tcp:3000 tcp:3000 lets the device reach a server running on the host machine.
This is invaluable for React Native and Flutter hot-reload workflows.
Sniffing Traffic Over ADB
Combine forward with a proxy tool like mitmproxy to inspect HTTPS traffic without rooting.
Wireless Debugging without cables
Initial USB Pairing
Connect once via USB, then run adb tcpip 5555 to switch the daemon into TCP mode.
Connecting Over Wi-Fi
Find the device IP in Settings > Network, then run adb connect 192.168.1.25:5555.
Unplug the cable and continue debugging across the room.
Reconnecting After Reboot
Enable the “ADB over network” toggle in Developer Options on rooted ROMs to persist the setting.
Scripting and Automation
Bash Automation
Wrap repetitive sequences in shell functions stored in ~/.bashrc for one-word deployments.
Python Integration
Use the pure-python adb-shell library to control devices programmatically without subprocess calls.
Combine with pytest for automated UI testing on real hardware.
Gradle Tasks
Define custom Gradle tasks that invoke adb install and adb shell am instrument for CI pipelines.
Security Implications and Best Practices
RSA Key Management
Revoke old keys by deleting adbkey and adbkey.pub in ~/.android to force fresh pairing.
Network Exposure
Never leave adb tcpip 5555 enabled on public Wi-Fi; always run adb usb when you finish.
Device Encryption
Ensure full-disk encryption is active so that adb pull cannot read sensitive files if the screen is locked.
Troubleshooting Common Errors
Device Not Found
Swap cables, try a USB 2.0 port, and check dmesg on Linux to confirm kernel recognition.
Unauthorized State
Revoke USB debugging authorizations in Developer Options and re-accept the RSA key.
Offline Status
Kill-server and start-server to reset the ADB daemon on the host side.
Hidden Features and Easter Eggs
Screen Recording
adb shell screenrecord /sdcard/demo.mp4 captures 720p video at 30 fps without third-party apps.
Set –bit-rate 6M for higher quality or –time-limit 30 to stop automatically.
Changing System Settings
adb shell settings put global animator_duration_scale 0 disables animations for faster testing.
Mock Locations
Enable mock locations with adb shell app_process set com.example.mockgps, then feed coordinates via telnet to the emulator.
Integration with Android Studio
Device Explorer
Android Studio embeds an ADB client, letting you drag-and-drop files directly into /data/data/package/.
Logcat Window
Color-coded log levels and search filters reduce the need for terminal windows.
Profiler Integration
Click “Profile” in the run configuration to launch CPU and memory profilers over ADB without manual commands.
Using ADB with Rooted Devices
Remounting Partitions
adb root && adb remount rewrites /system as read-write so you can push modified framework jars.
Magisk Module Installation
adb push module.zip /sdcard/Download, then open Magisk Manager and flash from storage.
Boot Image Extraction
adb pull /dev/block/bootdevice/by-name/boot boot.img grabs the untouched boot image for patching.
ADB Shell Scripting Recipes
Batch Uninstall Bloatware
for pkg in $(adb shell pm list packages | grep oem); do adb uninstall –user 0 $pkg; done
Nightly Database Backup
adb shell “run-as com.example.app tar -czf /sdcard/backup.tgz /data/data/com.example.app/databases”
Automated Screenshot Testing
adb shell screencap -p /sdcard/shot.png && adb pull /sdcard/shot.png test/$(date +%s).png
Performance Benchmarking with ADB
Frame Timing
adb shell dumpsys gfxinfo com.example.app produces a CSV of frame durations you can import into Google Sheets.
Battery Historian
adb bugreport bugreport.zip uploads a complete system snapshot for offline analysis with the Battery Historian web tool.
Thermal Throttling
cat /sys/class/thermal/thermal_zone0/temp inside adb shell returns millidegree values to detect overheating during tests.
ADB in Continuous Integration
GitHub Actions
Use reactivecircus/android-emulator-runner to boot an emulator and run adb-connected tests in the cloud.
Docker Containers
Package platform-tools into a lightweight Alpine image to share the exact same ADB version across team members.
Parallel Testing
Execute adb devices -l, parse serial numbers, and shard test suites across multiple physical devices using pytest-xdist.
Extending ADB with Custom Binaries
Pushing Custom Executables
Cross-compile ARM64 binaries with the NDK, then adb push mytool /data/local/tmp/.
Making Binaries Persistent
Move the binary to /system/xbin on rooted devices and chmod 755 to keep it after reboots.
Creating Wrapper Scripts
Write tiny shell wrappers that expose high-level commands like adb mytool –reset-wifi.
Future-Proofing Your ADB Workflow
Version Pinning
Lock platform-tools to a specific release in CI to avoid surprises when Google drops legacy commands.
Monitoring Release Notes
Subscribe to the Android Studio release feed; every major update usually ships new adb features like improved install speed.
Testing Beta SDKs
Run adb –version after each update to confirm the daemon on the device is still compatible with the host client.