Remote Debugging on Android with Chrome

Set up remote debugging

To begin remote debugging, you will need:

• For browser tabs: Android 4.0+ and Chrome for Android.
• For Android apps: Android 4.4+ and a WebView configured for debugging.
• A USB cable to plug in your Android device
• Chrome 32 or later installed on your development machine

1. Enable USB debugging on your Android device

On your Android device, go to Settings > Developer options.

In Developer options, confirm that USB debugging is checked:

2. Enable USB discovery in Chrome

On your desktop Chrome browser, go to chrome://inspect. Alternatively, to get to the same screen, you can select Chrome menu > Tools > Inspect Devices.

Confirm that Discover USB Devices is checked:

3. Connect your device via USB

Connect your mobile device to the development machine using a USB cable.

If you are developing on Windows, install the appropriate USB driver for your device. See OEM USB Drivers on the Android Developers site.

After connecting, you may see an alert on the device requesting permission for USB debugging from your computer:

To avoid seeing this alert each time you debug, check Always allow from this computer. Tap OK.

4. Debug a remote web view

Once you have set up your device for debugging over USB, the chrome://inspect page displays every connected device, along with its open tabs and debug-enabled WebViews:

Find the tab or WebView you're interested in and click the inspect link to open DevTools on it:

Open new browser tabs on the remote device by typing the URL in the text input field, then click Open.

Troubleshooting

• On your device, verify you have USB debugging turned on. When you connect your device to a laptop, there will be a "USB debugging connected" item in the notification drawer of your phone or tablet.
• On your desktop, verify you are using Chrome version 32 or later. You can check the version number in chrome://version.
• If USB debugging is on but chrome://inspect doesn't show your device, check that Discover USB devices is checked. If so, unplug the device and try revoking all the USB authorizations in the Android Developer options to retry. Be sure to connect the device directly to your machine, bypassing any hubs.
• If you're running a web server on your development machine, and network restrictions prevent your mobile device from accessing the server, try enabling port forwarding or setting up a virtual host map.
• Lastly, if things still are not working, you may have to try the legacy workflow for remote debugging via the adb binary from the Android SDK.

Debug browser tabs

When inspecting a remote browser tab in Chrome for Android, the element you are mousing over in the DevTools window will highlight the element on your device in real time. In fact, turn on inspect mode by clicking the icon, and then tap on your device screen.

Similarly, editing scripts or executing commands from the DevTools console affects the page being inspected on your device. You can also also use all of the other panels, such as Timeline and Profiles.

Debugging tips

• Reload the remote page from the DevTools window using F5 (or Cmd+R on Mac).
• Keep the device on a real cellular network to view the network waterfall in the Network panel under actual network conditions.
• The hardware on mobile devices often run your content much slower, so use the Timeline to analyze how to optimize rendering and CPU for the best effect.

Notes

• Closing the DevTools window has no effect on the remote device.
• Chrome will prevent your screen from going to sleep while remote debugging. Be aware that whilst useful, this makes your device less secure.
• You may notice that the version of the DevTools you have access to during remote debugging differs to the version you have running on your development machine. This is because the tools are synchronized with the Chrome on Android version in use.

Debug WebViews

Starting Android 4.4 (KitKat), you can use the DevTools to debug the contents of Android WebViews inside native Android applications.

The procedure for debugging WebViews is very similar to what was outlined in the Set up your device for remote debugging section except the Enable USB web debugging setting in Chrome doesn't affect WebViews.

Configure WebViews for debugging

To debug the contents of your WebView, you need to enable it programmatically from within your application by calling setWebContentsDebuggingEnabled, a static method on the WebView class.

if(Build.VERSION.SDK_INT >= Build.VERSION_CODES.KITKAT) {
    WebView.setWebContentsDebuggingEnabled(true);
}

This setting applies to all of the application's WebViews. Note that web debugging is not affected by the state of the debuggable flag in the application's manifest. If you want to enable web debugging only when debuggable is true, test the flag at runtime.

if(Build.VERSION.SDK_INT >= Build.VERSION_CODES.KITKAT) {
    if ( 0 != ( getApplcationInfo().flags &= ApplicationInfo.FLAG_DEBUGGABLE ) ) {
        WebView.setWebContentsDebuggingEnabled(true);
    }
}

Open a WebView in DevTools

Go to chrome://inspect in Chrome to get a list of debuggable WebViews, along with a graphic representing the WebView's size and position relative to the device's screen. If your WebViews have titles set, those will show as well. Click inspect on the WebView you wish to debug and use the DevTools as you would for a remote browser tab.

Screencasting

Screencasting lets you bring the experience of your device onto your machine. This allows you to keep your attention on one screen instead of switching back and forth between the device and the DevTools. As of KitKat 4.4.3, screencasting in now also available for Android WebViews.

While debugging a remote device, you will see a screencast icon in the DevTools toolbar:

Clicking on the screencast icon opens up a panel on your computer displaying your device's screen:

Watch a video of screencasting in action:

Interacting with the screencast

You can interact with the screencast of your device in a number of ways.

• Type on your machine's keyboard and these keystrokes are sent to the device
• Click to tap. Clicks will be sent to the device as proper touch events.
• Scroll by mousewheel, trackpad, or by flinging the content with your pointer.
• Inspect Element by selecting the Inspect Element button or by pressing Cmd + Shift + C
• Zoom with a simulated pinch gesture with Cmd + Click with two fingers + Drag
• Resize the pane that screencast is in to better size its contents.
• Transparent portions of the screencast are covered by things like the omnibox and keyboard. Only page content is being screencasted.

Note: The screencast feature does have a performance overhead, due to continuously capturing frames. Disable screencast if you're testing framerate-sensitive situations.

Port forwarding

Commonly you have a web server running on your local development machine, and you want to connect to that site from your device. If the mobile device and the development machine are on the same network, this is straightforward. But this may be difficult in some cases, like on a restricted corporate network.

Chrome for Android supports port fowarding making this workflow very simple to do. It works by creating a listening TCP port on your mobile device that maps to a particular TCP port on your development machine. The traffic through the forwarded port travels over USB, so it doesn't depend on the mobile device's network configuration.

Enable port forwarding

This procedure assumes that you already have remote debugging configured and working. On your development machine within Chrome:

1. Open chrome://inspect.
2. Click Port Forwarding button at the top.
3. In the Device port field, enter the port number the Android should device listen on (defaults to 8080).
4. In the Host field, add the IP (or hostname) and port number where your web application is running. This location can be any local location accessible from your development machine. Currently, it is limited to ports over 1024 and under 65535 (inclusive).
5. Make sure to check Enable port forwarding before hitting Done.

On chrome://inspect you should now see a green circle indicating your port forwarding is succssful. Now, enter in your local URL into the Open tab field and hit Go to open it on your device's browser.

You should see the content being served by your development machine:

Virtual host mapping

Follow the instructions for virtual host mapping to preview customised local domains (something other than localhost) on your device. Consider the following use cases for local development to understand where this is useful:

• You use a customised domain during development such as http://local.dev configured through any number of means, such as virtual hosts on your WebServer (e.g. MAMP).
• You add a hosts file entry such as 127.0.0.1 production.com as the third party JavaScript SDK on your page only works on a whitelisted domain.

To configure virtual host mapping with Chrome for Android, the device will need to communicate with a proxy installed on the host machine.

1. Open Wi-Fi settings.
2. Long-press the current network. (The proxy setting is per-network.)
3. Select Modify network.
4. Tap the Show advanced options checkbox below IP Address.
5. Proxy settings will appear. Select Manual.
6. Set Proxy hostname to localhost.
7. Set Proxy port to a port that Android will let you use, for example 9000.
8. Tap Save.

1. Install proxy software such as Charles Proxy (free trial available) or Squid.
2. Make note of the port the proxy is using. In Charles, you can access this via Proxy > Proxy Settings and making note of the port number in the HTTP Proxy > Port field.
3. Navigate to chrome://inspect/#devices on Google Chrome.
4. Select Port forwarding.
5. Enter 9000 in the Port field.
6. Enter localhost:1234 where 1234 is the port retrieved in step 2.
7. Ensure the Enable port forwarding checkbox is checked.

The steps above are required once per development session. Once port forwarding has been configured to forward requests to the host machine's proxy (from the device), you can load local domains on Chrome for Android just as you would on the host machine.

Additional information

Remote debugging and ADB

DevTools supports direct USB debugging of connected devices. You no longer need to configure ADB or the ADB plugin to see all instances of Chrome and the Chrome-powered WebView on devices connected to your system. This functionality works on all operating systems: Windows, Mac, Linux and Chrome OS.

If you use the adb binary for other reasons, please note the direct USB connection between Chrome and the device may interrupt an adb connection that you may be trying to establish. To fix, just uncheck the Discover USB Devices checkbox, unplug the device, and plug it back in, before establishing your connection via adb.

Remote debugging for DevTools extension developers

For information on the interaction protocol we use for our remote debugging, please see the Debugger Protocol documentation and chrome.debugger.