Android Debug Bridge (adb) is a versatile command line tool that lets you communicate with an emulator instance or connected Android device. It facilitates a variety of device actions, such as installing and debugging apps, and it provides access a Unix shell that you can use to run a variety of commands on an emulator or connected device. It is a client-server program that includes three components:
adb
is included in the Android SDK Platform-Tools package. You
can download this package with the SDK Manager, which installs
it at android_sdk/platform-tools/
. Or if you want
the standalone Android SDK Platform-Tools package, you can
download it here.
When you start an adb client, the client first checks whether there is an adb server process already running. If there isn't, it starts the server process. When the server starts, it binds to local TCP port 5037 and listens for commands sent from adb clients—all adb clients use port 5037 to communicate with the adb server.
The server then sets up connections to all running emulator/device instances. It locates emulator/device instances by scanning odd-numbered ports in the range 5555 to 5585, the range used by emulators/devices. Where the server finds an adb daemon, it sets up a connection to that port. Note that each emulator/device instance acquires a pair of sequential ports — an even-numbered port for console connections and an odd-numbered port for adb connections. For example:
Emulator 1, console: 5554
Emulator 1, adb: 5555
Emulator 2, console: 5556
Emulator 2, adb: 5557
and so on...
As shown, the emulator instance connected to adb on port 5555 is the same as the instance whose console listens on port 5554.
Once the server has set up connections to all emulator instances, you can use adb commands to access those instances. Because the server manages connections to emulator/device instances and handles commands from multiple adb clients, you can control any emulator/device instance from any client (or from a script).
To use adb with a device connected over USB, you must enable USB debugging in the device system settings, under Developer options.
On Android 4.2 and higher, the Developer options screen is hidden by default. To make it visible, go to Settings > About phone and tap Build number seven times. Return to the previous screen to find Developer options at the bottom.
On some devices, the Developer options screen may be located or named differently.
You can now connect your device with USB. You can verify that your device is
connected by executing adb devices
from the
android_sdk/platform-tools/
directory. If connected,
you'll see the device name listed as a "device."
Note: When you connect a device running Android 4.2.2 or higher, the system shows a dialog asking whether to accept an RSA key that allows debugging through this computer. This security mechanism protects user devices because it ensures that USB debugging and other adb commands cannot be executed unless you're able to unlock the device and acknowledge the dialog.
For more information about connecting to a device over USB, read Run Apps on a Hardware Device.
adb is usually used over USB. However, it is also possible to use over Wi-Fi, as described here.
Connect your Android device and adb host computer to a common Wi-Fi network accessible to both. Beware that not all access points are suitable; you may need to use an access point whose firewall is configured properly to support adb.
Note: If you are attempting to connect to an Android Wear device, force it to connect to Wi-Fi by shutting off Bluetooth on the phone connected to it.
$ adb tcpip 5555
$ adb connect device_ip_address
$ adb devices List of devices attached device_ip_address:5555 device
You're now good to go!
If the adb connection is ever lost:
adb connect
step again.
adb kill-server
Then start over from the beginning.
Before issuing adb commands, it is helpful to know what emulator/device instances are connected to the adb server. You can generate a list of attached emulators/devices using the devices
command:
adb devices
In response, adb prints this status information for each instance:
type-console-port
.
Here's an example serial number: emulator-5554
offline
— the instance is not connected to adb or is not responding.device
— the instance is now connected to the adb server. Note that this state does not
imply that the Android system is fully booted and operational, since the instance connects to adb
while the system is still booting. However, after boot-up, this is the normal operational state of
an emulator/device instance.no device
— there is no emulator/device connected.
The output is formatted like this:
List of devices attached serial_number state
Here's an example showing the devices
command and its output:
adb devices List of devices attached emulator-5554 device emulator-5556 device emulator-5558 device
If multiple emulator/device instances are running, you must specify a target instance
when issuing adb commands. To do so, use the -s
option in the commands. The usage
for the -s
option is:
adb -s serial_number command
As shown, you specify the target instance for a command using its adb-assigned serial number.
You can use the devices
command to obtain the serial numbers of running
emulator/device instances. For example:
adb -s emulator-5556 install helloWorld.apk
Note that, if you issue a command without specifying a target emulator/device instance while multiple devices are available, adb generates an error.
If you have multiple devices available (hardware or emulated), but only one is an emulator,
simply use the -e
option to send commands to the emulator. Likewise if there's multiple
devices but only one hardware device attached, use the -d
option to send commands to
the hardware device.
You can use adb to copy an application from your development computer and install it on an emulator/device instance. To do so, use the install
command. With the command, you must specify the path to the APK file that you want to install:
adb install path_to_apk
For more information about how to create an APK file that you can install on an emulator/device instance, see Build and Run Your App.
Note that, if you are using Android Studio, you do not need to use adb (or aapt) directly to install your application on the emulator/device. Instead, Android Studio handles the packaging and installation of the application for you.
You can use the forward
command to set up arbitrary port forwarding — forwarding of requests on a specific host port to a different port on an emulator/device instance. Here's how you would set up forwarding of host port 6100 to emulator/device port 7100:
adb forward tcp:6100 tcp:7100
You can also use adb to set up forwarding to named abstract UNIX domain sockets, as illustrated here:
adb forward tcp:6100 local:logd
You can use the adb commands pull
and push
to copy files to
and from an emulator/device instance. Unlike the install
command,
which only copies an APK file to a specific location, the pull
and push
commands let you copy arbitrary directories and files to any location in an
emulator/device instance.
To copy a file or directory (and its sub-directories) from the emulator or device, use
adb pull remote local
To copy a file or directory (and its sub-directories) to the emulator or device, use
adb push local remote
In the commands, local
and remote
refer to the
paths to the target files/directory on your development machine (local) and on the
emulator/device instance (remote). For example:
adb push foo.txt /sdcard/foo.txt
In some cases, you might need to terminate the adb server process and then restart it to resolve the problem (e.g., if adb does not respond to a command).
To stop the adb server, use the adb kill-server
command.
You can then restart the server by issuing any other adb command.
You can issue adb commands from a command line on your development machine or from a script. The usage is:
adb [-d|-e|-s serial_number] command
If there's only one emulator running or only one device connected, the adb command is
sent to that device by default. If multiple emulators are running and/or multiple devices are
attached, you need to use the -d
, -e
, or -s
option to specify the target device to which the command should be directed.
The table below lists all of the supported adb commands and explains their meaning and usage.
Table 1. Available adb commands
Category | Command | Description | Comments |
---|---|---|---|
Target Device | -d |
Direct an adb command to the only attached USB device. | Returns an error if more than one USB device is attached. |
-e |
Direct an adb command to the only running emulator instance. | Returns an error if more than one emulator instance is running. | |
-s serial_number |
Direct an adb command a specific emulator/device instance, referred to by its adb-assigned serial number (such as "emulator-5556"). | See Directing Commands to a Specific Emulator/Device Instance. | |
General | devices |
Prints a list of all attached emulator/device instances. | See Querying for Emulator/Device Instances for more information. |
help |
Prints a list of supported adb commands. | ||
version |
Prints the adb version number. | ||
Debug | logcat [option] [filter-specs] |
Prints log data to the screen. | |
bugreport |
Prints dumpsys , dumpstate , and logcat data to the screen, for the purposes of bug reporting. |
||
jdwp |
Prints a list of available JDWP processes on a given device. | You can use the forward jdwp:pid port-forwarding specification to connect to a specific JDWP process. For example: adb forward tcp:8000 jdwp:472 jdb -attach localhost:8000
|
|
Data | install path_to_apk |
Pushes an Android application (specified as a full path to an APK file) to an emulator/device. | |
pull remote local |
Copies a specified file from an emulator/device instance to your development computer. | ||
push local remote |
Copies a specified file from your development computer to an emulator/device instance. | ||
Ports and Networking | forward local remote |
Forwards socket connections from a specified local port to a specified remote port on the emulator/device instance. | Port specifications can use these schemes:
|
ppp tty [parm]... |
Run PPP over USB.
Note that you should not automatically start a PPP connection. |
||
Scripting | get-serialno |
Prints the adb instance serial number string. | See Querying for Emulator/Device Instances for more information. |
get-state |
Prints the adb state of an emulator/device instance. | ||
wait-for-device |
Blocks execution until the device is online — that is, until the instance state is device . |
You can prepend this command to other adb commands, in which case adb will wait until the emulator/device instance is connected before issuing the other commands. Here's an example:
adb wait-for-device shell getpropNote that this command does not cause adb to wait until the entire system is fully booted. For that reason, you should not prepend it to other commands that require a fully booted system. As an example, the install requires the Android package manager, which is available only after the system is fully booted. A command such as
adb wait-for-device install app.apkwould issue the install command as soon as the emulator or device instance connected to the adb server, but before the Android system was fully booted, so it would result in an error. |
|
Server | start-server |
Checks whether the adb server process is running and starts it, if not. | |
kill-server |
Terminates the adb server process. | ||
Shell | shell |
Starts a remote shell in the target emulator/device instance. | See Issue shell commands for more information. |
shell shell_command |
Issues a shell command in the target emulator/device instance and then exits the remote shell. |
You can use the shell
command to issue device commands through adb, with or without entering
the adb remote shell on the emulator/device. To issue a single command without entering a
remote shell, use the shell
command like this:
adb [-d|-e|-s serial_number] shell shell_command
Or enter a remote shell on an emulator/device like this:
adb [-d|-e|-s serial_number] shell
When you are ready to exit the remote shell, press Control + D or type
exit
.
The shell command binaries are stored in the file system of the emulator or
device, at /system/bin/
.
am
)Within an adb shell, you can issue commands with the activity manager (am
) tool to
perform various system actions, such as start an activity, force-stop a process,
broadcast an intent, modify the device screen properties, and more. While in a shell,
the syntax is:
am command
You can also issue an activity manager command directly from adb without entering a remote shell. For example:
adb shell am start -a android.intent.action.VIEW
Table 2. Available activity manager commands
Command | Description |
---|---|
start [options] intent
|
Start an Activity specified by intent . See the Specification for intent arguments. Options are:
|
startservice [options] intent
|
Start the Service specified by intent . See the Specification for intent arguments. Options are:
|
force-stop package
|
Force stop everything associated with package (the app's package name).
|
kill [options] package
|
Kill all processes associated with package
(the app's package name). This command kills only
processes that are safe to kill and that will not impact the user
experience.
Options are:
|
kill-all
|
Kill all background processes. |
broadcast [options] intent
|
Issue a broadcast intent. See the Specification for intent arguments. Options are:
|
instrument [options] component
|
Start monitoring with an Instrumentation instance.
Typically the target component
is the form test_package/runner_class . Options are:
|
profile start process file
|
Start profiler on process , write results to file .
|
profile stop process
|
Stop profiler on process .
|
dumpheap [options] process file
|
Dump the heap of process , write to file . Options are:
|
set-debug-app [options] package
|
Set application package to debug. Options are:
|
clear-debug-app
|
Clear the package previous set for debugging with set-debug-app .
|
monitor [options]
|
Start monitoring for crashes or ANRs. Options are:
|
screen-compat {on|off} package
|
Control screen
compatibility mode of package .
|
display-size [reset|widthxheight]
|
Override emulator/device display size.
This command is helpful for testing your app across different screen sizes by mimicking a small
screen resolution using a device with a large screen, and vice versa.
Example: |
display-density dpi
|
Override emulator/device display density.
This command is helpful for testing your app across different screen densities on high-density
screen environment using a low density screen, and vice versa.
Example: |
to-uri intent
|
Print the given intent specification as a URI. See the Specification for intent arguments. |
to-intent-uri intent
|
Print the given intent specification as an intent: URI. See the Specification for intent arguments. |
For activity manager commands that take a intent
argument, you can
specify the intent with the following options:
Show all
-a action
-d data_uri
-t mime_type
-c category
-n component
-f flags
setFlags()
.
--esn extra_key
-e|--es extra_key extra_string_value
--ez extra_key extra_boolean_value
--ei extra_key extra_int_value
--el extra_key extra_long_value
--ef extra_key extra_float_value
--eu extra_key extra_uri_value
--ecn extra_key extra_component_name_value
ComponentName
object.
--eia extra_key extra_int_value[,extra_int_value...]
--ela extra_key extra_long_value[,extra_long_value...]
--efa extra_key extra_float_value[,extra_float_value...]
--grant-read-uri-permission
FLAG_GRANT_READ_URI_PERMISSION
.
--grant-write-uri-permission
FLAG_GRANT_WRITE_URI_PERMISSION
.
--debug-log-resolution
FLAG_DEBUG_LOG_RESOLUTION
.
--exclude-stopped-packages
FLAG_EXCLUDE_STOPPED_PACKAGES
.
--include-stopped-packages
FLAG_INCLUDE_STOPPED_PACKAGES
.
--activity-brought-to-front
FLAG_ACTIVITY_BROUGHT_TO_FRONT
.
--activity-clear-top
FLAG_ACTIVITY_CLEAR_TOP
.
--activity-clear-when-task-reset
FLAG_ACTIVITY_CLEAR_WHEN_TASK_RESET
.
--activity-exclude-from-recents
FLAG_ACTIVITY_EXCLUDE_FROM_RECENTS
.
--activity-launched-from-history
FLAG_ACTIVITY_LAUNCHED_FROM_HISTORY
.
--activity-multiple-task
FLAG_ACTIVITY_MULTIPLE_TASK
.
--activity-no-animation
FLAG_ACTIVITY_NO_ANIMATION
.
--activity-no-history
FLAG_ACTIVITY_NO_HISTORY
.
--activity-no-user-action
FLAG_ACTIVITY_NO_USER_ACTION
.
--activity-previous-is-top
FLAG_ACTIVITY_PREVIOUS_IS_TOP
.
--activity-reorder-to-front
FLAG_ACTIVITY_REORDER_TO_FRONT
.
--activity-reset-task-if-needed
FLAG_ACTIVITY_RESET_TASK_IF_NEEDED
.
--activity-single-top
FLAG_ACTIVITY_SINGLE_TOP
.
--activity-clear-task
FLAG_ACTIVITY_CLEAR_TASK
.
--activity-task-on-home
FLAG_ACTIVITY_TASK_ON_HOME
.
--receiver-registered-only
FLAG_RECEIVER_REGISTERED_ONLY
.
--receiver-replace-pending
FLAG_RECEIVER_REPLACE_PENDING
.
--selector
-d
and -t
options to set the intent data and type.
URI component package
pm
)Within an adb shell, you can issue commands with the package manager (pm
) tool to
perform actions and queries on application packages installed on the device. While in a shell,
the syntax is:
pm command
You can also issue a package manager command directly from adb without entering a remote shell. For example:
adb shell pm uninstall com.example.MyApp
Table 3. Available package manager commands.
Command | Description |
---|---|
list packages [options] filter
|
Prints all packages, optionally only
those whose package name contains the text in filter . Options:
|
list permission-groups
|
Prints all known permission groups. |
list permissions [options] group
|
Prints all known permissions, optionally only
those in group . Options:
|
list instrumentation [options]
|
List all test packages. Options:
|
list features
|
Prints all features of the system. |
list libraries
|
Prints all the libraries supported by the current device. |
list users
|
Prints all users on the system. |
path package
|
Print the path to the APK of the given package .
|
install [options] path
|
Installs a package (specified by path ) to the system. Options:
|
uninstall [options] package
|
Removes a package from the system. Options:
|
clear package
|
Deletes all data associated with a package. |
enable package_or_component
|
Enable the given package or component (written as "package/class"). |
disable package_or_component
|
Disable the given package or component (written as "package/class"). |
disable-user [options] package_or_component
|
Options:
|
grant package_name permission
|
Grant a permission to an app. On devices running Android 6.0 (API level 23) and higher, may be any permission declared in the app manifest. On devices running Android 5.1 (API level 22) and lower, must be an optional permission defined by the app. |
revoke package_name permission
|
Revoke a permission from an app. On devices running Android 6.0 (API level 23) and higher, may be any permission declared in the app manifest. On devices running Android 5.1 (API level 22) and lower, must be an optional permission defined by the app. |
set-install-location location
|
Changes the default install location. Location values:
Note: This is only intended for debugging; using this can cause applications to break and other undesireable behavior. |
get-install-location
|
Returns the current install location. Return values:
|
set-permission-enforced permission [true|false]
|
Specifies whether the given permission should be enforced. |
trim-caches desired_free_space
|
Trim cache files to reach the given free space. |
create-user user_name
|
Create a new user with the given user_name ,
printing the new user identifier of the user.
|
remove-user user_id
|
Remove the user with the given user_id ,
deleting all data associated with that user
|
get-max-users
|
Prints the maximum number of users supported by the device. |
The screencap
command is a shell utility for taking a screenshot of a device display.
While in a shell, the syntax is:
screencap filename
To use the screencap
from the command line, type the following:
$ adb shell screencap /sdcard/screen.png
Here's an example screenshot session, using the adb shell to capture the screenshot and the
pull
command to download the file from the device:
$ adb shell shell@ $ screencap /sdcard/screen.png shell@ $ exit $ adb pull /sdcard/screen.png
The screenrecord
command is a shell utility for recording the display of devices
running Android 4.4 (API level 19) and higher. The utility records screen activity to an MPEG-4
file.
Note: Audio is not recorded with the video file.
A developer can use this file to create promotional or training videos. While in a shell, the syntax is:
screenrecord [options] filename
To use screenrecord
from the command line, type the following:
$ adb shell screenrecord /sdcard/demo.mp4
Stop the screen recording by pressing Control + C, otherwise the recording stops automatically
at three minutes or the time limit set by --time-limit
.
To begin recording your device screen, run the screenrecord
command to record
the video. Then, run the pull
command to download the video from the device to the host
computer. Here's an example recording session:
$ adb shell shell@ $ screenrecord --verbose /sdcard/demo.mp4 (press Control + C to stop) shell@ $ exit $ adb pull /sdcard/demo.mp4
The screenrecord
utility can record at any supported resolution and bit rate you
request, while retaining the aspect ratio of the device display. The utility records at the native
display resolution and orientation by default, with a maximum length of three minutes.
There are some known limitations of the screenrecord
utility that you should be aware
of when using it:
Table 4. screenrecord
options
Options | Description |
---|---|
--help
|
Displays command syntax and options |
--size widthxheight
|
Sets the video size: 1280x720 . The default value is the device's native
display resolution (if supported), 1280x720 if not. For best results, use a size supported
by your device's Advanced Video Coding (AVC) encoder. |
--bit-rate rate |
Sets the video bit rate for the video, in megabits per second. The default value is 4Mbps.
You can increase the bit rate to improve video quality, but doing so results in larger movie
files. The following example sets the recording bit rate to 6Mbps:
screenrecord --bit-rate 6000000 /sdcard/demo.mp4 |
--time-limit time |
Sets the maximum recording time, in seconds. The default and maximum value is 180 (3 minutes). |
--rotate |
Rotates the output 90 degrees. This feature is experimental. |
--verbose |
Displays log information on the command-line screen. If you do not set this option, the utility does not display any information while running. |
Starting in Android 7.0 (API level 24) the Android Runtime (ART) collects execution profiles for installed apps, which are used to optimize app performance. You might want to examine the collected profiles to understand which methods are determined to be frequently executed and which classes are used during app startup.
To produce a text form of the profile information, use the command:
$ adb shell cmd package dump-profiles package
To retrieve the file produced, use:
$ adb pull /data/misc/profman/package.txt
For a list of all the available shell programs, use the following command:
adb shell ls /system/bin
Help is available for most of the commands.
Table 5 lists some of the more common adb shell commands.
Table 5. Some other adb shell commands
Shell Command | Description | Comments |
---|---|---|
dumpsys |
Dumps system data to the screen. | The Dalvik Debug Monitor Server (DDMS) tool offers an integrated debug environment that you may find easier to use. |
dumpstate |
Dumps state to a file. | |
logcat [option]... [filter-spec]... |
Enables system and app logging and prints output to the screen. | |
dmesg |
Prints kernel debugging messages to the screen. | |
start |
Starts (restarts) an emulator/device instance. | |
stop |
Stops execution of an emulator/device instance. |