Build and run your app

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

When you want to see how your app looks and behaves on a device, you need to build and run it. Android Studio sets up new projects so that you can deploy your app to a virtual or a physical device with just a few clicks.

This overview focuses on how to use Android Studio to build and run your app for the purposes of testing and debugging. For information on how to use Android Studio to build your app so that it can be released to users, see Build your app for release to users. For more detailed information about managing and customizing your build, with or without Android Studio, see Configure your build.

Basic build and run

To build and run your app, follow these steps:

  1. In the toolbar, select your app from the run configurations drop-down menu.
  2. From the target device drop-down menu, select the device that you want to run your app on.

    Target device drop-down menu.

    If you don't have any devices configured, then you need to either create an Android Virtual Device to use the Android Emulator or connect a physical device.

  3. Click Run .

Android Studio will warn you if you attempt to launch your project to a device that has an error or a warning associated with it. Iconography and stylistic changes differentiate between errors (device selections that result in a broken configuration) and warnings (device selections that may result in unexpected behavior but are still runnable).

Monitor the build process

You can view details about the build process by clicking View > Tool Windows > Build (or by clicking Build in the tool window bar). The window displays the tasks that Gradle executes in order to build your app, as shown in figure 1.

Figure 1. The Build output window in Android Studio

  1. Build tab: Displays the tasks Gradle executes as a tree, where each node represents either a build phase or a group of task dependencies. If you receive build-time or compile-time errors, inspect the tree and select an element to read the error output, as shown in figure 2.

    Figure 2. Inspect the Build output window for error messages

  2. Sync tab: Displays tasks that Gradle executes to sync with your project files. Similar to the Build tab, if you encounter a sync error, select elements in the tree to find more information about the error.
  3. Restart: Performs the same action as selecting Build > Make Project by generating intermediate build files for all modules in your project.
  4. Toggle view: Toggles between displaying task execution as a graphical tree and displaying more detailed text output from Gradle—this is the same output you see in the Gradle Console window on Android Studio 3.0 and earlier.

If your build variants use product flavors, Gradle also invokes tasks to build those product flavors. To view the list of all available build tasks, click View > Tool Windows > Gradle (or click Gradle in the tool window bar).

If an error occurs during the build process, Gradle may recommend some command-line options to help you resolve the issue, such as --stacktrace or --debug. To use command-line options with your build process:

  1. Open the Settings or Preferences dialog:
    • On Windows or Linux, select File > Settings from the menu bar.
    • On Mac OSX, select Android Studio > Preferences from the menu bar.
  2. Navigate to Build, Execution, Deployment > Compiler.
  3. In the text field next to Command-line Options, enter your command-line options.
  4. Click OK to save and exit.

Gradle applies these command-line options the next time you try building your app.

Advanced build and run features

The default way your app is deployed by Android Studio, covered in the preceding section, should be sufficient to test a simple app. For more advanced use cases, you can toggle various aspects of how your app is built and run:

  • You can deploy your app in debug mode by clicking Debug . Running your app in debug mode allows you to set breakpoints in your code, examine variables and evaluate expressions at run time, and run debugging tools. To learn more, see Debug your app.

  • If you have a larger, more complex app, using Apply Changes instead of clicking Run can save you time because you can avoid restarting your app every time you want to deploy a change. For more information about Apply Changes, see Deploy incrementally with Apply Changes on this page.

  • If you're using Compose, Live Edit allows you to update composables in real time, without re-clicking Run, so you can focus on writing UI code with minimal interruption. For more information, see Live Edit on this page.

  • If you have an app with multiple build variants, or versions, you can choose which build variant to deploy by using the Build Variants tool window. For more information about running a specific build variant, see Change the build variant on this page.

  • To fine tune app installation, launch, and test options, you can change the run/debug configuration. The run/debug configuration specifies whether to deploy your app from an APK or an Android App Bundle, the module to run, package to deploy, activity to start, target device, emulator settings, logcat options, and more. For more information on how to create custom run/debug configurations, see Create run/debug configurations.

  • You should try using Android Studio for your development needs, but you can also deploy your app to a virtual or physical device from the command line. For more information, see Build your app from the command line.

Deploy incrementally with Apply Changes

In Android Studio 3.5 and higher, Apply Changes lets you push code and resource changes to your running app without restarting your app—and, in some cases, without restarting the current activity. This flexibility helps you control how much of your app is restarted when you want to deploy and test small, incremental changes while preserving your device's current state. Apply Changes uses capabilities in the Android JVMTI implementation that are supported on devices running Android 8.0 (API level 26) or higher. To learn more about how Apply Changes works, see Android Studio Project Marble: Apply Changes.

Requirements

Apply Changes actions are only available when you meet the following conditions:

  • You build the APK of your app using a debug build variant.
  • You deploy your app to a target device or emulator that runs Android 8.0 (API level 26) or higher.

Use Apply Changes

Use the following options when you want to deploy your changes to a compatible device:

Apply Changes and Restart Activity Apply Changes and Restart Activity icon

Attempts to apply both your resource and code changes by restarting your activity but without restarting your app. Generally, you can use this option when you've modified code in the body of a method or modified an existing resource.

You can also perform this action by pressing Ctrl+Alt+F10 (or Control+Shift+Command+R on macOS).

Apply Code Changes Apply Code Changes icon

Attempts to apply only your code changes without restarting anything. Generally, you can use this option when you've modified code in the body of a method but you have not modified any resources. If you've modified both code and resources, use Apply Changes and Restart Activity instead.

You can also perform this action by pressing Ctrl+F10 (or Control+Command+R on macOS).

Run Run icon

Deploys all changes and restarts the app. Use this option when the changes that you have made cannot be applied using either of the Apply Changes options. To learn more about the types of changes that require an app restart, see Limitations of Apply Changes.

Enable Run fallback for Apply Changes

After you've clicked either Apply Changes and Restart Activity or Apply Code Changes, Android Studio builds a new APK and determines whether the changes can be applied. If the changes can't be applied and would cause Apply Changes to fail, Android Studio prompts you to Run Run icon your app again instead. However, if you don't want to be prompted every time this occurs, you can configure Android Studio to automatically rerun your app when changes can't be applied.

To enable this behavior, follow these steps:

  1. Open the Settings or Preferences dialog:

    • On Windows or Linux, select File > Settings from the menu bar.
    • On macOS, select Android Studio > Preferences from the menu bar.
  2. Navigate to Build, Execution, Deployment > Deployment.

  3. Select the checkboxes to enable automatic Run fallback for either of the Apply Changes actions.

  4. Click OK.

Platform-dependent changes

Some features of Apply Changes depend on specific versions of the Android platform. To apply these kinds of changes, your app must be deployed to a device running that version of Android (or higher).

Type of change Minimum platform version
Adding a method Android 11

Limitations of Apply Changes

Apply Changes is designed to speed up the app deployment process. However, there are some limitations for when it can be used. If you encounter any issues while using Apply Changes, file a bug.

Code changes that require app restart

Some code and resource changes cannot be applied until the app is restarted, including the following:

  • Adding or removing a field
  • Removing a method
  • Changing method signatures
  • Changing modifiers of methods or classes
  • Changing class inheritance
  • Changing values in enums
  • Adding or removing a resource
  • Changing the app manifest
  • Changing native libraries (SO files)
Libraries and plugins

Some libraries and plugins automatically make changes to your app's manifest files or to resources that are referenced in the manifest. These automatic updates can interfere with Apply Changes in the following ways:

  • If a library or plugin makes changes to your app's manifest, you can't use either Apply Code Changes Apply Code Changes icon or Apply Changes and Restart Activity Apply Changes and Restart Activity icon and have to restart your app before you can see your changes.
  • If a library or plugin makes changes to your app's resource files, you can't use Apply Code Changes Apply Code Changes icon, and you must use Apply Changes and Restart Activity Apply Changes and Restart Activity icon to see your changes.

You can avoid these limitations by disabling all automatic updates for your debug build variants.

For example, Crashlytics updates app resources with a unique build ID during every build, which prevents you from using Apply Code Changes Apply Code Changes icon and requires you to restart your app's activity to see your changes. You can disable this behavior so that you can use Apply Code Changes alongside Crashlytics with your debug builds.

Code that directly references content in an installed APK

If your code directly references content from your app's APK that's installed on the device, that code can cause crashes or misbehave after clicking Apply Code Changes Apply Code Changes icon. This behavior occurs because when you click Apply Code Changes, the underlying APK on the device is replaced during installation. In these cases, you can click Apply Changes and Restart Activity Apply Changes and Restart Activity icon or Run Run icon, instead.

Live Edit (experimental)

Live Edit is an experimental feature in the Android Studio Flamingo canary releases that allows you to update composables in emulators and physical devices in real time. When you update a composable function, your changes are applied in your device or emulator as you make that change. This functionality minimizes context switches between writing and building your app, allowing you to focus on writing code longer without interruption.

Live Edit is focused on UI- and UX-related code changes. Live Edit doesn't support changes such as method signature updates, adding new methods, or class hierarchy changes. For more information, see Limitations.

This feature is not a replacement for building and running your application or Apply Changes. Instead, it's designed to optimize your workflow as you build, deploy, and iterate to develop Compose UI.

The best practice workflow is as follows:

  1. Set up your application so that it can be Run.
  2. Live Edit as much as possible, until you need to make a change that Live Edit doesn't support--for example, adding new methods while the app is running.
  3. After you make an unsupported change, Run your app to resume Live Editing.

Gif of using Live Edit with a device

Figure 3. Each time you make an edit that is supported by Live Edit, the running app on your device or emulator is updated in real time.

Get started with Live Edit

To quickly get started, follow these steps to create an empty Compose Activity, enable Live Edit for your project, and make changes with Live Edit.

Set up your new project
  1. Before you begin, ensure that you have the latest canary version of Android Studio Electric Eel installed, and that the API level of your physical device or emulator is at least 30.

  2. Open Android Studio and select New Project in the Welcome to Android Studio popup. If you already have a project open, you can create a new one by navigating to File > New > New Project.

  3. Choose the Empty Compose Activity template for Phone and Tablet, and then click Next.

    Template selection in Android Studio Figure 4. Templates you can choose from. For Live Edit, choose Empty Compose Activity.

  4. Enter the following, and then click Finish.

    • Name: HelloWorld
    • Package name: com.example.helloworld
    • Save location: Default.
    • Language: Kotlin
    • Minimum SDK: Default

    Example project settings from Step 4 entered in AS Figure 5. Example project settings.

Enable Live Edit
  1. In the IDE, navigate to the settings to enable Live Edit.

    • On Windows or Linux, navigate to File > Settings > Editor > Live Edit.
    • On macOS, navigate to Android Studio > Preferences > Editor > Live Edit.

    Live Edit checkbox UI in Android Studio settings Figure 6. Select the Live Edit option from the settings.

  2. In the editor, open the MainActivity file, which is the entry point for your app.

  3. Click Run UI button to deploy your app, and then click Split on the top right of the editor to open the preview.

  4. After you turn on Live Edit, you should see the Live Edit green checkmark on the top right of the editor.

    Live Edit green checkmark UI

Make and review changes

In the editor, change the existing Greeting method in MainActivity to the following. Your changes appear instantaneously, as shown in figure 7.

@Composable
fun Greeting(name: String) {
    Text(text = "Hello $name!",
        Modifier.padding(80.dp) // Outer padding; outside background
            .background(color = Color.Cyan) // Solid element background color
            .padding(16.dp) // Inner padding; inside background, around text)
    )
}

Changes to Greeting method applied on a device

Figure 7. Live Edit changes to the Greeting method above appear instantly.

Troubleshooting

If you don't see your edits in the preview pane, Android Studio might have failed to update your edits. Check if the Live Edit UI indicator shows a paused icon, which indicates a compilation error.

Live Edit status UI

Figure 8. To see more information about the error and suggestions for how to resolve it, hover over Live Edit: ON in the UI.

Limitations

The following is a list of current limitations.

  • Live Edit requires a physical device or emulator that is running API level 30 or higher.
  • Live Edit only supports editing a function body, which means that you can't change the function name or the signature, add or remove a function, or change non-function fields.
  • Live Edit-modified classes might incur some performance penalty. We recommend that you Run your app and use a clean Release build if you are evaluating its performance.
  • You must perform a full Run in order for the debugger to operate on classes that you have modified with Live Edit.
  • A running app might crash when you edit it with Live Edit. If this happens, you can redeploy the app with the Run UI button button.
  • Live Edit doesn't perform any bytecode manipulation that's defined in your project's build file–for example, bytecode manipulation that would be applied when the project is built using the options in the Build menu or by clicking the Build or Run buttons.
  • Non-Composable functions are updated live on the device or emulator and a full recomposition is triggered. The full recomposition might not invoke the updated function. For non-composable functions, you must trigger the newly updated functions, or Run the app again.
  • Live Edit doesn't resume on app restarts. You must Run the app again.

Frequently asked questions

  • What is the current status of Live Edit?
    • Live Edit is available in the Android Studio Electric Eel canary channel as an experimental feature. You can turn it on or off by navigating to File > Settings > Editor > Live Edit (Android Studio > Preferences > Editor > Live Edit on macOS).
  • When should I use Live Edit?
    • Use Live Edit when you want to quickly see the effect of updates to UX elements (e.g. modifier updates, animations) on the overall app experience.
  • When should I avoid using Live Edit?
    • Live Edit is currently focused on UI- and UX-related code changes. Avoid using it for changes such as method signature updates, adding new methods, or class hierarchy changes, which it does not support. For more information, see Limitations.
  • When should I use Compose Preview?
    • Use Composition Preview when you're developing individual composables. Preview visualizes Compose elements and automatically refreshes to display the effect of code changes. Preview also supports viewing UI elements under different configurations and states (for example dark mode, locales, font scale).

Change the build variant

By default, Android Studio builds the debug version of your app, which is intended for use only during development, when you click Run.

To change the build variant Android Studio uses, select Build > Select Build Variant in the menu bar.

For projects without native/C++ code, the Build Variants panel has two columns: Module and Active Build Variant. The Active Build Variant value for the module determines which build variant the IDE deploys to your connected device and is visible in the editor.

Figure 9. The Build Variants panel has two columns for projects that do not have native/C++ code

To switch between variants, click the Active Build Variant cell for a module and choose the desired variant from the list field.

For projects with native/C++ code, the Build Variants panel has three columns: Module, Active Build Variant, and Active ABI. The Active Build Variant value for the module determines the build variant that the IDE deploys to your device and is visible in the editor. For native modules, the Active ABI value determines the ABI that the editor uses, but does not impact what is deployed.

Figure 10. The Build Variants panel adds the Active ABI column for projects with native/C++ code

To change the build variant or ABI, click the cell for the Active Build Variant or Active ABI column and choose the desired variant or ABI from the list. After you change the selection, the IDE syncs your project automatically. Changing either column for an app or library module will apply the change to all dependent rows.

By default, new projects are set up with two build variants: a debug and release variant. You need to build the release variant to prepare your app for public release.

To build other variations of your app, each with different features or device requirements, you can define additional build variants.

Conflicts in Android Studio’s Build Variants dialog

In Android Studio’s Build Variants dialog, you might see error messages indicating conflicts between build variants, such as the following:

Build Variant window displaying variant conflict errors

This error does not indicate a build issue with Gradle – it is only indicating that the Android Studio IDE itself cannot resolve symbols between the variants of the selected modules.

For example, if you have a module M1 that depends on variant v1 of module M2, but M2 has variant v2 selected in the IDE, you have unresolved symbols in the IDE. Let’s say that M1 depends on a class Foo which is only available in v1. When v2 is selected, that class is not known by the IDE and it will fail to resolve it and show errors in the code of M1.

These error messages appear because the IDE cannot load code for multiple variants simultaneously. In terms of your app’s build, however, the variant selected in this dialog will have no effect because Gradle builds your app with the source code specified in your Gradle build recipes, not based on what’s currently loaded in the IDE.

Change the run/debug configuration

When you run your app for the first time, Android Studio uses a default run configuration. The run configuration specifies whether to deploy your app from an APK or an Android App Bundle, the module to run, package to deploy, activity to start, target device, emulator settings, logcat options, and more.

The default run/debug configuration builds an APK, launches the default project activity, and uses the Select Deployment Target dialog for target device selection. If the default settings don't suit your project or module, you can customize the run/debug configuration, or even create a new one, at the project, default, and module levels. To edit a run/debug configuration, select Run > Edit Configurations. For more information, see Create and Edit Run/Debug Configurations.