Run apps on a hardware device

Stay organized with collections Save and categorize content based on your preferences.

When building an Android app, it's important that you always test your app on a real device before releasing it to users. This page describes how to set up your development environment and Android device for testing and debugging over an Android Debug Bridge (ADB) connection.

Set up a device for development

Before you can start debugging on your device, decide if you want to connect the device to using a USB cable or Wi-Fi. Then do the following:

  1. On the device, open the Settings app, select Developer options, and then enable USB debugging (if applicable).

  2. Set up your system to detect your device.

    • Chrome OS: No additional configuration required.
    • macOS: No additional configuration required.
    • Ubuntu Linux: There are two things that need to be set up correctly: each user that wants to use adb needs to be in the plugdev group, and the system needs to have udev rules installed that cover the device.

      plugdev group: If you see an error message that says you're not in the plugdev group, you'll need to add yourself to the plugdev group:

      sudo usermod -aG plugdev $LOGNAME
      

      Note that groups only get updated on login, so you'll need to log out for this change to take effect. When you log back in, you can use id to check that you're now in the plugdev group.

      udev rules: The android-sdk-platform-tools-common package contains a community-maintained default set of udev rules for Android devices. To install:

      apt-get install android-sdk-platform-tools-common
      
    • Windows: Install a USB driver for ADB (if applicable). For an installation guide and links to OEM drivers, see the Install OEM USB drivers document.

Connect to your device using USB

When you are set up and plugged in over USB, you can click Run in Android Studio to build and run your app on the device.

You can also use adb to issue commands, as follows:

  • Verify that your device is connected by running the adb devices command from your android_sdk/platform-tools/ directory. If connected, you'll see the device listed.
  • Issue any adb command with the -d flag to target your device.

Connect to your device using Wi-Fi

Android 11 (and later) supports deploying and debugging your app wirelessly from your workstation via Android Debug Bridge (adb). For example, you can deploy your debuggable app to multiple remote devices without physically connecting your device via USB and contending with common USB connection issues, such as driver installation.

To use wireless debugging, you need to pair your device to your workstation using a pairing code. To begin, complete the following steps:

  1. Ensure that your workstation and device are connected to the same wireless network.
  2. Ensure that your device is running Android 11 or higher. For more informaton, see Check & update your Android version.
  3. Ensure that you have Android Studio Bumblebee Canary. You can download it here.
  4. On your workstation, update to the latest version of the SDK Platform-Tools.

To connect to your device, follow these steps:

  1. Open Android Studio and select Pair Devices Using Wi-Fi from the run configurations dropdown menu.
    Run configurations dropdown menu
    Figure 1. Run configurations dropdown menu.

    The Pair devices over Wi-Fi window pops up, as shown below.
    Screenshot of the pair devices over Wi-Fi popup window
    Figure 2. Popup window to pair devices using QR code or pairing code.
  2. Enable developer options on your device.
  3. Enable debugging over Wi-Fi on your device.
    Screenshot of
      a pixel phone showing the Wireless debugging systems setting.
    Figure 3. Screenshot of the Wireless debugging setting on a Google Pixel phone.
  4. Tap on Wireless debugging and pair your device:
    1. To pair your device with a QR code, select Pair device with QR code and scan the QR code obtained from above.
    2. To pair your device with a pairing code, select Pair device with pairing code from the Pair devices over Wi-Fi window above. On your device, select Pair using pairing code and take note of the six digit pin code. Once your device appears on the Pair devices over Wi-Fi window, you can select Pair and enter the six digit pin code shown on your device.
      Screenshot of example pin code entry
      Figure 4. Example of six digit pin code entry.
  5. After you are paired, you can attempt to deploy your app to your device.

    To pair a different device or to forget this device on your workstation, navigate to Wireless debugging on your device, tap on your workstation name under Paired devices, and select Forget.

Troubleshoot device connection

If your device is not connecting to Android Studio, try the following to resolve the issue.

Troubleshoot with the Connection Assistant

The Connection Assistant provides step-by-step instructions to help you set up and use a device over the ADB connection.

To start the assistant, choose Tools > Troubleshoot Device Connections.

The Connection Assistant provides instructions, in-context controls, and a list of connected devices in a series of pages in the Assistant panel. Use the Next and Previous buttons at the bottom of the Assistant panel to work through the pages as needed:

  • Connect your device over USB: The Connection Assistant begins by prompting you to connect your device over USB, and it provides a Rescan USB devices button with which you can start a new scan for connected devices.
  • Enable USB debugging: The Connection Assistant then tells you how to enable USB debugging in the on-device developer options.
  • Restart the ADB server: Finally, if you still don't see your device on the list of available devices, you can use the Restart ADB server button on the last page of the Connection Assistant. Restarting the ADB server also causes ADB to scan for devices again. If you still don't see your device on the list of available devices, try the troubleshooting steps in the next section of this page.

Resolve USB connection issues

If the Connection Assistant is not detecting your device over USB, you can try the following troubleshooting steps to resolve the issue:

Check that Android Studio can connect to the Android Emulator

To check if the issue is being caused by a connection problem between Android Studio and the Android Emulator, follow these steps:

  1. Open the AVD Manager.
  2. Create a new AVD if you don't already have one.
  3. Run the emulator using your AVD.
  4. Do one of the following:

Check the USB cable

To check if the issue is being caused by a faulty USB cable, follow the steps in this section.

If you have another USB cable:

  1. Connect the device using the secondary cable.
  2. Check if the Connection Assistant can now detect the device.
  3. If the device is not detected, try the primary cable again.
  4. If the device still isn't detected, assume that the problem is with the device and check if the device is set up for development.

If you don't have another USB cable but you do have another Android device:

  1. Connect the secondary device to your computer.
  2. If the Connection Assistant can detect the secondary device, assume that the problem is with the primary device and check if the device is set up for development.

    If the secondary device is not detected, the problem might be with the USB cable.

Check if the device is set up for development

To check if the issue is being caused by settings on the device, follow these steps:

  1. Follow the steps in the Set up a device for development section.
  2. If this does not resolve the problem, contact the device OEM's customer support for help. Tell the customer support representative that the device won't connect to Android Studio using ADB.

Resolve wireless connection issues

If you are having issues connecting to your device wirelessly, you can try the following troubleshooting steps to resolve the issue.

Check if your workstation and device meet the prerequisites

To meet the prerequisites for wireless debugging, ensure that:

  1. Your workstation and device are connected to the same wireless network.
  2. Your device is running Android 11 or higher. For more information, see Check & update your Android version.
  3. You have Android Studio Bumblebee. You can download it here.
  4. You have the latest version of the SDK Platform Tools on your workstation.

Check for other known issues

The following is a list of current known issues with wireless debugging in Android Studio and how to resolve them.

  1. Wi-Fi is not connecting: Some Wi-Fi networks, such as corporate Wi-Fi networks, may block p2p connections and not allow you to connect over Wi-Fi. Try connecting with a cable or another Wi-Fi network.
  2. ADB over Wi-Fi sometimes turns off automatically: This can happen if the device either switches Wi-Fi networks or disconnects from the network.

RSA security key

When you connect a device running Android 4.2.2 (API level 17) or higher to your computer, 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.