1page.title=Android Debug Bridge 2parent.title=Tools 3parent.link=index.html 4page.tags=adb 5@jd:body 6 7<div id="qv-wrapper"> 8<div id="qv"> 9 <h2>In this document</h2> 10<ol> 11 <li><a href="#Enabling">Enabling adb Debugging</a></li> 12 <li><a href="#issuingcommands">Syntax</a></li> 13 <li><a href="#commandsummary">Commands</a></li> 14 <li><a href="#devicestatus">Querying for Emulator/Device Instances</a></li> 15 <li><a href="#directingcommands">Directing Commands to a Specific Emulator/Device Instance</a></li> 16 <li><a href="#move">Installing an Application</a></li> 17 <li><a href="#forwardports">Forwarding Ports</a></li> 18 <li><a href="#copyfiles">Copying Files to or from an Emulator/Device Instance</a></li> 19 <li><a href="#stopping">Stopping the adb Server</a></li> 20 <li><a href="#wireless">Wireless usage</a></li> 21</ol> 22 23</div> 24</div> 25 26<p>Android Debug Bridge (adb) is a versatile command line tool that lets you communicate with an 27emulator instance or connected Android-powered device. It is a client-server program that includes 28three components: </p> 29 30<ul> 31 <li>A client, which runs on your development machine. You can invoke a client from a shell 32by issuing an adb command. Other Android tools such as the ADT plugin and DDMS also create 33adb clients. </li> 34 <li>A server, which runs as a background process on your development machine. The server 35manages communication between the client and the adb daemon running on an emulator or device. </li> 36 <li>A daemon, which runs as a background process on each emulator or device instance. </li> 37</ul> 38 39<p>You can find the {@code adb} tool in {@code <sdk>/platform-tools/}.</p> 40 41<p>When you start an adb client, the client first checks whether there is an adb server 42process already running. If there isn't, it starts the server process. When the server starts, 43it binds to local TCP port 5037 and listens for commands sent from adb clients—all adb 44clients use port 5037 to communicate with the adb server. </p> 45 46<p>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: </p> 47 48<p style="margin-left:2em"> 49Emulator 1, console: 5554<br/> 50Emulator 1, adb: 5555<br> 51Emulator 2, console: 5556<br> 52Emulator 2, adb: 5557<br> 53and so on... 54</p> 55 56<p>As shown, the emulator instance connected to adb on port 5555 is the same as the instance 57whose console listens on port 5554. </p> 58 59<p>Once the server has set up connections to all emulator instances, you can use adb commands to 60access those instances. Because the server manages connections to emulator/device 61instances and handles commands from multiple adb clients, you can control any emulator/device 62instance from any client (or from a script).</p> 63 64 65<h2 id="Enabling">Enabling adb Debugging</h2> 66 67<p>In order to use adb with a device connected over USB, you must enable 68<strong>USB debugging</strong> in the device system settings, under <strong> 69Developer options</strong>.</p> 70 71<p>On Android 4.2 and higher, the Developer options screen is 72hidden by default. To make it visible, go to 73<b>Settings > About phone</b> and tap <b>Build number</b> seven times. Return to the previous 74screen to find <strong>Developer options</strong> at the bottom.</p> 75 76<p>On some devices, the Developer options screen may be located or named differently.</p> 77 78<p class="note"><strong>Note:</strong> When you connect a device running Android 4.2.2 or higher 79to your computer, the system shows a dialog asking whether to accept an RSA key that allows 80debugging through this computer. This security mechanism protects user devices because it ensures 81that USB debugging and other adb commands cannot be executed unless you're able to unlock the 82device and acknowledge the dialog. This requires that you have adb version 1.0.31 (available with 83SDK Platform-tools r16.0.1 and higher) in order to debug on a device running Android 4.2.2 or 84higher.</p> 85 86<p>For more information about connecting to a device over USB, read 87<a href="{@docRoot}tools/device.html">Using Hardware Devices</a>.</p> 88 89 90 91 92<h2 id="issuingcommands">Syntax</h2> 93 94<p>You can issue adb commands from a command line on your development machine or from a script. 95The usage is: </p> 96 97<pre class="no-pretty-print"> 98adb [-d|-e|-s <serialNumber>] <command> 99</pre> 100 101<p>If there's only one emulator running or only one device connected, the adb command is 102sent to that device by default. If multiple emulators are running and/or multiple devices are 103attached, you need to use the <code>-d</code>, <code>-e</code>, or <code>-s</code> 104option to specify the target device to which the command should be directed. </p> 105 106 107 108<h2 id="commandsummary">Commands</h2> 109 110<p>The table below lists all of the supported adb commands and explains their meaning and usage. </p> 111 112<p class="table-caption"><strong>Table 1.</strong> Available adb commands</p> 113<table> 114<tr> 115 <th>Category</th> 116 <th>Command</th> 117 <th>Description</th> 118 <th>Comments</th> 119</tr> 120 121<tr> 122<td rowspan="3">Target Device</td> 123<td><code>-d</code></td> 124<td>Direct an adb command to the only attached USB device.</td> 125<td>Returns an error if more than one USB device is attached.</td> 126</tr> 127 128<tr> 129<td><code>-e</code></td> 130<td>Direct an adb command to the only running emulator instance.</td> 131<td>Returns an error if more than one emulator instance is running. </td> 132</tr> 133 134<tr> 135<td><code>-s <serialNumber></code></td> 136<td>Direct an adb command a specific emulator/device instance, referred to by its adb-assigned serial number (such as "emulator-5556").</td> 137<td>See <a href="#directingcommands">Directing 138Commands to a Specific Emulator/Device Instance</a>.</td> 139</tr> 140 141<tr> 142<td rowspan="3">General</td> 143<td><code>devices</code></td> 144<td>Prints a list of all attached emulator/device instances.</td> 145<td>See <a href="#devicestatus">Querying for Emulator/Device Instances</a> for more information.</td> 146</tr> 147 148<tr> 149<td><code>help</code></td> 150<td>Prints a list of supported adb commands.</td> 151<td> </td> 152</tr> 153 154<tr> 155<td><code>version</code></td> 156<td>Prints the adb version number. </td> 157<td> </td> 158</tr> 159 160<tr> 161<td rowspan="3">Debug</td> 162<td ><code>logcat [option] [filter-specs]</code></td> 163<td>Prints log data to the screen. </td> 164<td> </td> 165</tr> 166 167<tr> 168<td><code>bugreport</code></td> 169<td>Prints <code>dumpsys</code>, <code>dumpstate</code>, and <code>logcat</code> data to the screen, for the purposes of bug reporting. </td> 170<td> </td> 171</tr> 172 173<tr> 174<td><code>jdwp</code></td> 175<td>Prints a list of available JDWP processes on a given device. </td> 176<td>You can use the <code>forward jdwp:<pid></code> port-forwarding specification to connect to a specific JDWP process. For example: <br> 177 <code>adb forward tcp:8000 jdwp:472</code><br> 178 <code>jdb -attach localhost:8000</code></p> 179 </td> 180</tr> 181 182<tr> 183<td rowspan=3">Data</td> 184<td><code>install <path-to-apk></code></td> 185<td>Pushes an Android application (specified as a full path to an .apk file) to an emulator/device. </td> 186<td> </td> 187</tr> 188 189<tr> 190<td><code>pull <remote> <local></code></td> 191<td>Copies a specified file from an emulator/device instance to your development computer. </td> 192<td> </td> 193</tr> 194 195<tr> 196<td><code>push <local> <remote></code></td> 197<td>Copies a specified file from your development computer to an emulator/device instance. </td> 198<td> </td> 199</tr> 200 201<tr> 202<td rowspan="2">Ports and Networking</td> 203<td><code>forward <local> <remote></code></td> 204<td>Forwards socket connections from a specified local port to a specified remote port on the emulator/device instance. </td> 205<td>Port specifications can use these schemes: 206<ul><li><code>tcp:<portnum></code></li> 207<li><code>local:<UNIX domain socket name></code></li> 208<li><code>dev:<character device name></code></li> 209<li><code>jdwp:<pid></code></li></ul> 210</td> 211</tr> 212 213<tr> 214<td><code>ppp <tty> [parm]...</code></td> 215<td>Run PPP over USB. 216<ul> 217<li><code><tty></code> — the tty for PPP stream. For example <code>dev:/dev/omap_csmi_ttyl</code>. </li> 218<li><code>[parm]... </code> — zero or more PPP/PPPD options, such as <code>defaultroute</code>, <code>local</code>, <code>notty</code>, etc.</li></ul> 219 220<p>Note that you should not automatically start a PPP connection. </p></td> 221<td></td> 222</tr> 223 224<tr> 225<td rowspan="3">Scripting</td> 226<td><code>get-serialno</code></td> 227<td>Prints the adb instance serial number string.</td> 228<td rowspan="2">See <a href="#devicestatus">Querying for Emulator/Device Instances</a> for more information. </td> 229</tr> 230 231<tr> 232<td><code>get-state</code></td> 233<td>Prints the adb state of an emulator/device instance.</td> 234</td> 235</tr> 236 237<tr> 238<td><code>wait-for-device</code></td> 239<td>Blocks execution until the device is online — that is, until the instance state is <code>device</code>.</td> 240<td>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: 241<pre class="no-pretty-print">adb wait-for-device shell getprop</pre> 242 243Note that this command does <em>not</em> 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 <code>install</code> requires the Android package manager, which is available only after the system is fully booted. A command such as 244 245<pre class="no-pretty-print">adb wait-for-device install <app>.apk</pre> 246 247would issue the <code>install</code> 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. </td> 248</tr> 249 250 251 252<tr> 253<td rowspan="2">Server</td> 254<td><code>start-server</code></td> 255<td>Checks whether the adb server process is running and starts it, if not.</td> 256<td> </td> 257</tr> 258 259<tr> 260<td><code>kill-server</code></td> 261<td>Terminates the adb server process.</td> 262<td> </td> 263</tr> 264 265 266 267<tr> 268<td rowspan="2">Shell</td> 269<td><code>shell</code></td> 270<td>Starts a remote shell in the target emulator/device instance.</td> 271<td rowspan="2">See <a href="{@docRoot}tools/help/shell.html#shellcommands">ADB Shell Commands</a> for more information. </td> 272</tr> 273 274<tr> 275<td><code>shell [shellCommand]</code></td> 276<td>Issues a shell command in the target emulator/device instance and then exits the remote shell.</td> 277</tr> 278 279</table> 280 281 282 283 284 285 286 287 288 289 290<h2 id="devicestatus">Querying for Emulator/Device Instances</h2> 291 292<p>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 <code>devices</code> command: </p> 293 294 <pre class="no-pretty-print">adb devices</pre> 295 296<p>In response, adb prints this status information for each instance:</p> 297 298<ul> 299 <li>Serial number — A string created by adb to uniquely identify an emulator/device instance by its 300 console port number. The format of the serial number is <code><type>-<consolePort></code>. 301 Here's an example serial number: <code>emulator-5554</code></li> 302 <li>State — The connection state of the instance may be one of the following: 303 <ul> 304 <li><code>offline</code> — the instance is not connected to adb or is not responding.</li> 305 <li><code>device</code> — the instance is now connected to the adb server. Note that this state does not 306 imply that the Android system is fully booted and operational, since the instance connects to adb 307 while the system is still booting. However, after boot-up, this is the normal operational state of 308 an emulator/device instance.</li> 309 <li><code>no device</code> — there is no emulator/device connected. 310 </ul> 311 </li> 312</ul> 313 314<p>The output for each instance is formatted like this: </p> 315 316 <pre class="no-pretty-print">[serialNumber] [state]</pre> 317 318<p>Here's an example showing the <code>devices</code> command and its output:</p> 319 320 <pre class="no-pretty-print">adb devices 321List of devices attached 322emulator-5554 device 323emulator-5556 device 324emulator-5558 device</pre> 325 326 327 328 329 330 331<h2 id="directingcommands">Directing Commands to a Specific Emulator/Device Instance</h2> 332 333<p>If multiple emulator/device instances are running, you must specify a target instance 334when issuing adb commands. To do so, use the <code>-s</code> option in the commands. The usage 335for the <code>-s</code> option is:</p> 336 337<pre class="no-pretty-print">adb -s <serialNumber> <command> </pre> 338 339<p>As shown, you specify the target instance for a command using its adb-assigned serial number. 340You can use the <code>devices</code> command to obtain the serial numbers of running 341emulator/device instances. For example: </p> 342 343<pre class="no-pretty-print">adb -s emulator-5556 install helloWorld.apk</pre> 344 345<p>Note that, if you issue a command without specifying a target emulator/device instance 346while multiple devices are available, adb generates an error. 347 348<p>If you have multiple devices available (hardware or emulated), but only one is an emulator, 349simply use the {@code -e} option to send commands to the emulator. Likewise if there's multiple 350devices but only one hardware device attached, use the {@code -d} option to send commands to 351the hardware device. 352 353 354 355 356<h2 id="move">Installing an Application</h2> 357<p>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 <code>install</code> command. With the command, you must specify the path to the .apk file that you want to install:</p> 358 359<pre class="no-pretty-print">adb install <path_to_apk></pre> 360 361<p>For more information about how to create an .apk file that you can install on an emulator/device 362instance, see <a href="{@docRoot}tools/building/index.html">Building and Running</a></p> 363 364<p>Note that, if you are using the Eclipse IDE and have the ADT plugin installed, you do not need to use adb (or aapt) directly to install your application on the emulator/device. Instead, the ADT plugin handles the packaging and installation of the application for you. </p> 365 366 367 368 369 370 371<h2 id="forwardports">Forwarding Ports</h2> 372 373 <p>You can use the <code>forward</code> 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:</p> 374<pre class="no-pretty-print">adb forward tcp:6100 tcp:7100</pre> 375 <p>You can also use adb to set up forwarding to named abstract UNIX domain sockets, as illustrated here:</p> 376<pre class="no-pretty-print">adb forward tcp:6100 local:logd </pre> 377 378 379 380 381 382<h2 id="copyfiles">Copying Files to or from an Emulator/Device Instance</h2> 383 384<p>You can use the adb commands <code>pull</code> and <code>push</code> to copy files to 385and from an emulator/device instance. Unlike the <code>install</code> command, 386which only copies an APK file to a specific location, the <code>pull</code> and <code>push</code> 387commands let you copy arbitrary directories and files to any location in an 388emulator/device instance. </p> 389 390<p>To copy a file or directory (and its sub-directories) <em>from</em> the emulator or device, use</p> 391<pre class="no-pretty-print">adb pull <remote> <local></pre> 392 393<p>To copy a file or directory (and its sub-directories) <em>to</em> the emulator or device, use</p> 394 <pre class="no-pretty-print">adb push <local> <remote></pre> 395 396<p>In the commands, <code><local></code> and <code><remote></code> refer to the 397paths to the target files/directory on your development machine (local) and on the 398emulator/device instance (remote). For example: </p> 399<pre class="no-pretty-print">adb push foo.txt /sdcard/foo.txt</pre> 400 401 402 403 404<h2 id="stopping">Stopping the adb Server</h2> 405 406<p>In some cases, you might need to terminate the adb server process and then restart it 407to resolve the problem (e.g., if adb does not respond to a command).</p> 408 409<p>To stop the adb server, use the <code>kill-server</code> command. 410You can then restart the server by issuing any other adb command. </p> 411 412 413<h2 id="wireless">Wireless usage</h2> 414 415<p> 416adb is usually used over USB. However, it is also possible to use over 417Wi-Fi, as described here. 418</p> 419 420<ol> 421 422<li> 423<p>Connect your Android device and adb host computer 424to a common Wi-Fi network accessible to both. 425We have found that not all access points 426are suitable; you may need to use an access point 427whose firewall is configured properly to support adb.</p> 428 429<p class="note"><strong>Note: </strong>If you are attempting to connect 430to a Wear device, force it to connect to Wi-Fi by shutting off Bluetooth 431on the phone connected to it.</p> 432</li> 433 434<li> 435Connect the device to the host computer with a USB cable. 436</li> 437 438<li> 439Set the target device to listen for a TCP/IP connection on port 5555. 440<pre class="no-pretty-print"> 441$ adb tcpip 5555 442</pre> 443</li> 444 445<li> 446Disconnect the USB cable from the target device. 447</li> 448 449<li> 450Find the IP address of the Android device. For example, on a Nexus device, you can find 451the IP address at <strong>Settings</strong> > <strong>About tablet</strong> 452(or <strong>About phone</strong>) > <strong>Status</strong> > <strong>IP address</strong>. Or, 453on an Android Wear device, you can find the IP address at <strong>Settings</strong> > 454<strong>Wi-Fi Settings</strong> > <strong>Advanced</strong> > <strong>IP address</strong>. 455</li> 456 457<li> 458Connect to the device, identifying it by IP address. 459<pre class="no-pretty-print"> 460$ adb connect <device-ip-address> 461</pre> 462</li> 463 464 465<li> 466Confirm that your host computer is connected to the target device: 467<pre class="no-pretty-print"> 468$ adb devices 469List of devices attached 470<device-ip-address>:5555 device 471</pre> 472 473</ol> 474 475<p> 476You're now good to go! 477</p> 478 479<p> 480If the adb connection is ever lost: 481</p> 482 483<ol> 484 485<li> 486Make sure that your host is still connected to the same Wi-Fi network your Android device is. 487</li> 488 489<li> 490Reconnect by executing the "adb connect" step again. 491</li> 492 493<li> 494Or if that doesn't work, reset your adb host: 495<pre class="no-pretty-print"> 496adb kill-server 497</pre> 498and then start over from the beginning. 499</li> 500 501</ol> 502