7/8/25, 9:44 AM Debug a Wear OS app | Android Developers
Debug a Wear OS app
To debug your Wear OS app on a physical watch, connect your development machine to
the watch using Wi-Fi or Bluetooth. Alternatively, if your watch has a USB port, connect
using USB (/training/wearables/apps/creating#connect-watch-wired).
You can also test workflows that span multiple devices, such as a watch and a phone, if
your app requires this support. To learn more about how to set up a connection for
testing, visit connect a watch to a phone (/training/wearables/get-started/connect-phone).
Note: If you don't have a physical watch, you can also test and run your app on an emulator
(/training/wearables/get-started/creating#run-emulator) in Android Studio.
Update to the latest version of Wear OS link
To help verify that your app behaves as expected on the latest software, check that your
test device is running the most up-to-date version of Wear OS that your device supports.
To check for a system update on your test device, complete these steps:
1. Connect the device to a Wi-Fi network.
2. Start charging the device.
3. Wait for the device's battery to charge to 50% or higher.
4. On your test device, navigate to Settings > System > System updates.
If a system update is available, it'll be downloaded and installed onto your test
device.
Install a specific version of Wear OS (optional)
If your app's test case depends on a specific version of Wear OS, you can flash a software
image onto watches that support a USB data connection. For example, you can flash a
factory image (https://developers.google.com/android/images-watch) or a full OTA image
(https://developers.google.com/android/ota-watch) onto a Google Pixel Watch 3 or Google Pixel
Watch 2 device.
https://developer.android.com/training/wearables/get-started/debugging 1/7
7/8/25, 9:44 AM Debug a Wear OS app | Android Developers
Enable developer options on your watch
Before you can debug on your watch, enable developer options. You only need to do this
one time. Developer options remain enabled until you disable them. To enable developer
options, do the following:
1. Open the watch's Settings.
2. Tap System > About > Versions.
3. Tap the Build number item seven times.
4. A message appears confirming that you are now a developer.
Debug over Wi-Fi
Before you begin, enable developer options on the watch as described previously.
Connect the watch to a Wi-Fi network
1. Open the watch's Settings.
2. Tap Connectivity > Wi-Fi.
3. Choose a network and enter its password if necessary.
star Note: The watch and your development machine must be connected to the same network. Not
all access points are suitable. You may need to use an access point whose firewall is configured
properly to support adb.
Enable Wi-Fi debugging
1. Open the watch's Settings.
2. Tap Developer options > Debug over Wi-Fi.
3. After a moment, the screen displays the watch's IP address, such as
192.168.1.100 . You need this for the next step, so make a note of it.
Pair the debugger to the watch
https://developer.android.com/training/wearables/get-started/debugging 2/7
7/8/25, 9:44 AM Debug a Wear OS app | Android Developers
1. On your Wear OS device, find the wireless debugging options in system settings.
Select Pair new device.
2. Note the Wi-Fi pairing code and the IP address & port.
3. In a terminal window on your development machine, type the following command:
$ adb pair IP_ADDRESS edit:PORT edit
4. When prompted, enter the Wi-Fi pairing code from step 2. The terminal will output
whether pairing was successful. As an example:
Enter pairing code: 123456
Successfully paired to 192.168.1.100:5555
After pairing, the host computer appears in the list of Paired devices on your Wear OS
device's Wireless Debugging screen.
Connect the debugger to the watch
1. Connect your watch and development machine to the same network.
2. Connect the debugger to the watch using the watch's IP address and a port
number. For example, if the IP address is 192.168.1.100 and the port number is
5555 , the adb connect command and its response look like this:
adb connect 192.168.1.100:5555
connected to 192.168.1.100:5555
The watch is now connected to the debugger and you are ready to start debugging. Send
adb commands to the watch using the -s flag, specifying the watch's IP address and the
port number:
https://developer.android.com/training/wearables/get-started/debugging 3/7
7/8/25, 9:44 AM Debug a Wear OS app | Android Developers
adb -s 192.168.1.100:5555 <command>
If you are not using the emulator and have only one device connected for debugging, you
don't need to specify the address:
adb <command>
Debug over Bluetooth
Note: Bluetooth debugging works only for Android-paired watches running Wear OS 2.
Before you begin, pair the watch and phone and enable developer options
(#enable-dev-options) on the watch as described previously. Check that developer options
are enabled on the phone by opening the phone's Settings menu and looking for
Developer Options. If necessary, enable developer options
(/studio/debug/dev-options#enable) on the phone.
Enable USB debugging on the phone
1. Open the phone's Settings menu.
2. Select Developer Options and enable USB debugging.
Enable ADB or Bluetooth debugging on the watch
1. Open the watch's Settings menu.
2. Scroll to Developer Options.
3. Confirm that ADB debugging is enabled.
4. Enable Debug over Bluetooth.
https://developer.android.com/training/wearables/get-started/debugging 4/7
7/8/25, 9:44 AM Debug a Wear OS app | Android Developers
Enable Bluetooth debugging on the phone
1. On the phone, open the Wear OS companion app.
2. Scroll to Advanced Settings and tap to view the Advanced Settings options.
3. Enable Debugging over Bluetooth. The following status message appears under
the option:
Host: disconnected
Target: connected
At this point the development machine—the host—is not communicating with the watch—
the target. You need to complete the link.
Note: You can only debug with one device at a time. If you have multiple watches paired, Bluetooth
debugging is only enabled with the device selected on the main screen.
Connect the debugger to the watch
In this final step, you use everything: the debugger, the phone, and the watch.
1. Connect the phone to your development machine with a USB cable.
2. Run these two commands in the debugger:
adb forward tcp:4444 localabstract:/adb-hub
adb connect 127.0.0.1:4444
star Note: You must use the IP address 127.0.0.1. Use any available port on your development
machine, and use the same port in both commands. In this example, the port is 4444.
3. After you enter the connect command, the watch asks you to confirm that you are
allowing ADB Debugging.
https://developer.android.com/training/wearables/get-started/debugging 5/7
7/8/25, 9:44 AM Debug a Wear OS app | Android Developers
4. On the phone, check the status display in the Wear OS companion app for the
following:
Host: connected
Target: connected
The watch is now connected to the debugger, and you're ready to start debugging.
When you debug a watch using Bluetooth, adb always uses the IP address 127.0.0.1
plus the port that you assign. In this example, the port is 4444 . All adb commands use the
following format:
adb -s 127.0.0.1:4444 <command>
If you are not using the emulator and have only one device connected for debugging, you
don't need to specify the address:
adb <command>
Use screen record for Wear OS
If you develop on macOS, you can use the GitHub project Android tool for Mac
(https://github.com/mortenjust/androidtool-mac/blob/master/README.md) to record a video from
your Wear OS device.
Alternatively, record a video from your Wear OS device using the following steps:
1. Record raw frames on the watch:
adb shell screenrecord --time-limit 30 --output-format raw-frames --verbo
https://developer.android.com/training/wearables/get-started/debugging 6/7
7/8/25, 9:44 AM Debug a Wear OS app | Android Developers
2. Copy the raw file to your development machine:
adb pull /sdcard/video.raw video.raw
3. Use ffmpeg to convert the raw file to MP4:
ffmpeg -f rawvideo -vcodec rawvideo -s 400x400 -pix_fmt rgb24 -r 10 -i vi
star Note: Refer to the FFmpeg (https://www.ffmpeg.org/download.html) website for download and
installation instructions.
Refer to the following related resources:
Android Debug Bridge (adb) (/studio/command-line/adb)
Debug your app (/studio/debug)
Design principles (/training/wearables/design/design-principles)
Capture Wear UI screens (/training/wearables/get-started/screenshots)
Content and code samples on this page are subject to the licenses described in the Content License
(/license). Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
Last updated 2024-11-12 UTC.
https://developer.android.com/training/wearables/get-started/debugging 7/7
