Create and run an app on Wear OS

This page provides a guide for you to build your first app for Wear OS, using a template from Android Studio. The app showcases the different ways to view information at a glance on Wear OS devices, and introduces some best practices for developing apps on the platform.

This guide builds upon some prior knowledge about the Android platform and the Android Studio IDE. If you're completely new to Android, create an app using this codelab. To learn more about Android Studio's capabilities, visit the Meet Android Studio page.

Create a Wear OS app

After you download and install the latest version of Android Studio, complete the "new project" wizard:

  1. Open Android Studio, and then go to File > New > New Project. The New Project window appears.
  2. In the Templates pane, select Wear OS. Then, in the main pane, select Empty Wear App.
  3. Name your project, and then click Finish. Android Studio downloads the necessary dependencies and builds the initial version of your project.

  4. Go to Tools > SDK Manager, and install both of the following packages:

    • Android 14.0 ("UpsideDownCake) (API level 34), which includes the Wear OS 5 - ARM 64 v8a System Image and the Wear OS 5 - Intel x86 Atom_64 System Image.
    • Android 13.0 ("Tiramisu") (API level 33), which includes the Wear OS 4 ARM 64 v8a System Image and the Wear OS 4 Intel x86 Atom_64 System Image.

    To close the SDK Manager, click OK.

You're now ready to run your first app on Wear OS.

Run an app on the emulator

The easiest way to run your first Wear OS app is to configure an emulator.

Configure an emulator

To configure an emulator in Android Studio, complete the following steps:

  1. In the SDK Manager, Open the SDK Tools tab. Confirm that you have the latest version of Android SDK Platform-Tools.
  2. Go to Tools > Device Manager.
  3. Select Create (+). The Virtual Device Configuration wizard appears.
  4. In the Category pane, select Wear OS and choose a hardware profile, such as Wear OS Small Round. Click Next.

  5. For system images used outside of China, select the UpsideDownCake release name. This release targets Android 14.0 (Wear OS 5). For system images used in China, select the R release name. This release targets Android 11.0 (Wear OS 3). If you don't already have a Wear OS 5 system image installed that matches your device definition, click Download next to the Release Name to get it. Click Next.

    Note: System images for the Wear OS emulator include notices of third-party files and source code. You can view third-party notices for a particular system image by opening the NOTICE.txt file, which is in one of the following directories:

    • $ANDROID_HOME/system-images/android-API_VERSION_NUMBER/android-wear/ABI for emulators used outside of China.
    • $ANDROID_HOME/system-images/android-API_VERSION_NUMBER/android-wear-cn/ABI for emulators used in China.

  6. You can keep the default value for all the settings on this screen, unless you want to customize your emulator. Click Finish.

For more information about using emulators, see the guide about how to run apps on the Android Emulator.

Open the app in the emulator

  1. Go to Run > Select Device. Choose the emulator that you just created.
  2. In the Android Studio toolbar, click Run . The emulator starts and opens your app.
  3. After a few moments, you should see a "Hello..." message in the emulator.

Test Bluetooth audio using the emulator

On system images the run Wear OS 4 or higher, the emulator supports emulated Bluetooth, which lets you test Bluetooth audio across several use cases.

Recent system images only support 64-bit architectures

The emulator system images for Wear OS 4 and higher only support these 64-bit architectures: x86-64 and arm64-v8a. If you know or suspect that your app uses native code (that isn't written in the Kotlin or Java programming languages), check that your app includes both 32-bit and 64-bit native libraries.

Learn more about how to support 64-bit architectures.

Run an app on a physical watch (optional)

Running and debugging your app on an actual watch lets you better evaluate the total user experience. This is particularly important if your app relies on specific hardware, such as sensors or a GPU.

To run an app on a physical watch, prepare the device for testing, and then connect it to your development machine.

Prepare watch for testing

To prepare your watch for testing, enable ADB debugging by completing the following steps.

  1. On the watch, open the Settings menu.
  2. Go to the bottom of the menu. If no Developer options item appears, complete the following sub-steps. Otherwise, continue to the next step.
    1. Tap System > About or System > About > Versions.
    2. Find the Build number item and tap it seven times. If your watch is protected by a PIN or pattern, enter it when prompted to do so.
  3. From the Settings menu, tap Developer options.
  4. Enable the ADB debugging option.

Connect watch to development machine

Some watches let you connect over USB. Others require a wireless connection.

Set up a wired connection over USB

Connect the watch using the following steps:

  1. Using a USB cable, connect the watch to your development machine.
  2. On the watch, enable Always allow from this computer, and then tap OK.

Set up a wireless connection

If your watch lacks a USB port, learn how to connect a watch using Wi-Fi or Bluetooth.

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 (wired) data connection. For example, you can flash a factory image or a full OTA image onto a Google Pixel Watch 3 or Google Pixel Watch 2 device.

Open the app on the watch

  1. Go to Run > Select Device. Choose the watch that is connected to your machine.
  2. In the Android Studio toolbar, click Run . The emulator starts and opens your app.
  3. After a few moments, you should see a "Hello..." message appear on the watch.