Android Debug Bridge - ArchWiki

Jump to content

# Android Debug Bridge

From ArchWiki

Related articles

- Android

The Android Debug Bridge—adb(1)—is a command-line tool, that can be used to install, uninstall and debug applications, transfer files and access an Android device shell.

See also the official guide.

## Installation

adb is a part of the android-tools package and the Platform-Tools SDK package.

## Usage

### Connect a device

First you must enable Developer Mode on your device. To do so you must:

1. Go to Settings > About Phone, tap Build Number seven times until you get a popup that you have become a developer. Build number may be under a menu called Software info on newer Android OS versions.
2. Go to Developer Options and make sure Use developer options is on.

#### USB

To connect to a real device via adb with USB, you must:

- Plug in your Android device via USB.
- Go to Developer Options > Debugging and enable USB debugging.
- The device will ask to allow the computer with its fingerprint to connect. Checking allowing it permanently option will copy `~/.android/adbkey.pub` to the target device `/data/misc/adb/adb_keys` location.
- If adb recognizes your device—`adb devices` shows it as `device`—you are done. Otherwise see the instructions below and the #Troubleshooting section.

Tip

- systemd includes basic udev rules for Android devices to make adb and fastboot work out of the box. If your device does not show up, try to install the android-udev package with additional rules.
- Many devices' udev rules are included in libmtp, so if you have this installed, manual adding udev rules may not be necessary.
- For some devices, you may have to enable MTP on the device, before adb will work.
- Some other devices require enable PTP mode to work.
- Make sure your USB cable is capable of both charge and data. USB cables bundled with mobile devices might not include the USB data pin.

#### Wi-Fi

To connect to a real device via adb with Wi-Fi, you must:

- Make sure your device is on the same Wi-Fi network as your computer.
- Go to Developer Options > Debugging and enable Wireless debugging. Device IP address and dynamic connection Port will be displayed.
- Tap Pair device with pairing code. Random Pairing code, device IP address and dynamic pairing Port will be displayed. This port will be different than the one provided to connection and will be changed for each pairing attempt.
- Run `adb pair IP_address:Pairing_port Pairing_code`. See also adb(1) § NETWORKING.
- Run `adb connect IP_address:Connection_port`.
- You should see your computer listed under Paired Devices and your device listed in the `adb devices` output.

Note Devices running Android 10 or older do not support Wireless Debugging.

Dynamic port for network connection will be changed if you:

- turn off Use wireless debugging and then turn on it again,
- disable Wi-Fi and then reconnect back,
- lock and then unlock your device.

Note If you use dynamic port for network connection as described above and lock your device, connection will be closed (your device in the `adb devices` output list will be marked as `offline` and then disappear).

To use specific port for network connection—restart the `adbd` daemon on your device so it will listen on the specific port, see also adb(1) § SCRIPTING:

    $ adb tcpip 5555 && sleep 1 && adb connect IP_address

Tip

- `5555` is the default port, so port number in the `adb connect` command can be omitted.
- Small delay is needed, because the `adbd` daemon does not restart instantly.
- If you use specific port for network connection as described here and lock your device, connection will be kept (your device will not disappear from the `adb devices` output list).

### Transferring files

You can use adb to transfer files between the device and your computer. To transfer files to the device, use:

    $ adb push what_to_copy where_to_place

To transfer files from the device, use:

    $ adb pull what_to_pull where_to_place

Also see #Tools built on adb.

### udev rules

Each Android device has a USB vendor ID (VID) and product ID (PID). In the following example for HTC Evo vendor ID is 0bb4 and product ID is 0c8d:

    $ lsusb

    …
    Bus 002 Device 006: ID 0bb4:0c8d High Tech Computer Corp.
    …

See also lsusb(8), Hardware probe and the USB ID repository.

If your device USB ID is not included in the android-udev package, use the following template to create a custom udev rule by replacing `VENDOR_ID` and `PRODUCT_ID` with IDs of your device:

    /etc/udev/rules.d/51-android.rules

    ACTION!="remove", SUBSYSTEM=="usb", ATTR{idVendor}=="VENDOR_ID", MODE="0660", GROUP="adbusers", ENV{ID_DEBUG_APPLIANCE}="android"
    ACTION!="remove", SUBSYSTEM=="usb", ATTR{idVendor}=="VENDOR_ID", ATTR{idProduct}=="PRODUCT_ID", SYMLINK+="android_adb"
    ACTION!="remove", SUBSYSTEM=="usb", ATTR{idVendor}=="VENDOR_ID", ATTR{idProduct}=="PRODUCT_ID", SYMLINK+="android_fastboot"

Then reload the udev rules.

Note Unplugging and replugging the device back may also be necessary.

See also #no permissions.

### Backup and restore

This article or section is being considered for removal.

Reason: From the StackExchange answer by Robert:

- It is totally unclear if a backup was successful.
- `adb backup` on Android 12 only work if `targetSDK` is lower than 31 or the app is marked as `debuggable=true`. Apps downloaded from Play Store are never debuggable and Google enforces apps to set `targetSDK` to the latest API level. Therefore apps from Google Play Store that has been updated in 2022 or later should no longer allow app data backup using `adb backup`.
- Backup solutions for Android… require a rooted device. Android without root doesn't allow access to app data.

(Discuss in Talk:Android Debug Bridge)
Note `adb backup` and `adb restore` are deprecated and may be removed in a future release.

You can also backup and restore your device with adb. Moreover, no root user is required to follow the process. The commands below led to backup your device to a single file which can also be successively restored. To see the help help message for `adb backup` and `adb restore` parameters, run `adb shell bu help`.

The command parameters list for backup is:

    adb backup [-f <file>] [-apk|-noapk] [-shared|-noshared] [-all] [-system|nosystem] [<packages...>]

The command to create a backup is:

    $ adb backup -apk -shared -all -f backup_file_name.ab

Then confirm the process on your device's display and provide a password whether a backup password has been set before.

The command to restore a previous backup is:

    $ adb restore backup_file_name.ab

Warning Restoring operation will replace your device contents with the backup contents.

## Tools built on adb

- adbfs-rootless — Mount via FUSE an Android device connected via adb.

  Run `adbfs --help` to see the list of available options, read mount.fuse(8) § OPTIONS for their description.
  For example, to mount the primary storage instead of the root directory run:

      $ adbfs mount_point -o modules=subdir -o subdir=/storage/self/primary

  https://github.com/spion/adbfs-rootless || adbfs-rootless-gitAUR

- ADBManager — The program is designed for visual and easy management of the adb server and connection of Android devices. Allows you to monitor the status of the adb service, manage it, and control the list of connected devices. Allows you to manage your device: search for installed packages by part name, install, delete APK, screenshot, reboot (Normal, Bootloader, Recovery mode) and shutdown the device. For advanced users, there is an Android Shell terminal and an SD-Card file manager.

  https://github.com/AKotov-dev/adbmanager || adbmanagerAUR

- AndroidScreencast — View and control your Android device via adb from a PC.

  https://github.com/xSAVIKx/AndroidScreencast || androidscreencast-binAUR

- Aurynk — Application for managing Android devices, pairing via ADB, and mirroring screens using scrcpy. It features a native GTK4/libadwaita interface, device details, wireless pairing, tray integration, and screenshot capture.

  https://ishusinghse.github.io/aurynk/ || aurynkAUR

- Better ADB Sync — An rsync-like program to synchronize files between a computer and an Android device using the Android Debug Bridge protocol.

  https://github.com/jpstotz/better-adb-sync || better-adb-sync-gitAUR

- logcat-color3 — A colorful and highly configurable alternative to the standard `adb logcat` command.

  https://github.com/yan12125/logcat-color3 || logcat-color3AUR

- madbfs — A modern userspace filesystem for Android devices via adb, inspired by `adbfs-rootless`.

  https://github.com/mrizaln/madbfs || madbfs-binAUR

- QtScrcpy — Android real-time display control software.

  https://github.com/barry-ran/QtScrcpy || qtscrcpyAUR

- scrcpy — Display and control your Android device.

  https://github.com/Genymobile/scrcpy || scrcpy

## Troubleshooting

### Empty device list

Possible causes for your device to not show up.

USB connection:

- Not having enabled USB debugging on your device.
- Using a power only—charge-only—USB cable and not an USB data transfer cable.
- If you added udev rules, reloaded them, replugged your device, and adb still does not detect it—kill(1) and restart the adb server as root user and check devices again:

      # adb kill-server
      # adb start-server
      $ adb devices

Network connection:

- Connection was closed, because you use dynamic port for network connection and your device was locked.

### adb: more than one device/emulator

If you have several devices connected—i.e. the output of `adb devices` contains more than one `device`—then you can use the `ANDROID_SERIAL` environment variable to specify your desired device, for example:

    $ ANDROID_SERIAL=host:non-default_port adbfs mount_point

For more information, see Send commands to a specific device.

### insufficient permissions

If you see following error when running adb:

    E adb     : usb_libusb.cpp:571 failed to open device: Access denied (insufficient permissions)

check if you are in `adbusers` group.

### no permissions

If the device in the `adb devices` output shows up with the `no permissions` label, it probably has different vendor and product IDs with respect to the ones collected by android-udev. This can happen for instance when the device uses a custom ROM, or when it is switched from MTP to USB tethering mode, sideload and/or fastboot mode.

Verify the actual device USB ID and add udev rules.

### unauthorized

- If `adb devices` shows `unauthorized` next to your device, make sure that that device has debugging permission allowed on the device itself:
  - An Allow USB Debugging? dialog should be presented when you physically connect the device. Select Always Allow…, then tap OK.
  - If the dialog was never presented, try Settings > Developer Options > Revoke USB Debugging Authorizations, then tap OK, and repeat the steps in the #Connect a device section.
- If you still do not see the Allow USB Debugging? dialog, and the device is listed as `unauthorized`, then enter the Developer Options on the device and first uncheck USB Debugging and then check it again.

### Multicast DNS

Multicast DNS (mDNS) is not supported by android-tools—you will see the following error when running `adb mdns check`:

    error: unknown host service 'mdns:check'

and the following error when running `adb mdns services`:

    error: unknown host service 'mdns:services'

To use mDNS, switch to the android-sdk-platform-toolsAUR SDK package.

If you still encounter `error: unknown host service` — add the environment variable `ADB_MDNS_OPENSCREEN=1`.

Tip To connect automatically with a script, consider this gist.
Category:

- Android

Hidden category:

- Sections flagged with Template:Remove

Android Debug Bridge
Add topic