When you run, debug, or test your code, Android Studio uses a run/debug configuration to determine how to perform the operation. Typically, the initially-created configuration is sufficient to run or debug an app. However, you can modify and create new configurations, and modify the configuration templates to suit your development process as described on this page.
For more information, also see the following IntelliJ documentation:
Run/debug configurations specify details such as app installation, launch, and test options. You can define a configuration for one-time use, or save it for future use. After you save it, you can select the configuration from the Select Run/Debug Configuration drop-down list within the toolbar. Android Studio saves configurations as part of the project.
When you first create a project, Android Studio creates a run/debug configuration for the main activity based on the Android App template. To run or debug your project, you must always have at least one run/debug configuration defined. For this reason, we recommend that you don't delete the initially-created configuration.
Run/debug configurations and template changes apply to the current project only. You can share a run/debug configuration (but not a template) through your version control system. For more information about how to share a configuration, see Name and Share Configuration Options.
To open the Run/Debug Configurations dialog, select Run > Edit Configurations. The Run/Debug Configurations dialog appears, as shown in figure 1.
Figure 1. The Run/Debug Configurations dialog
The left panel of the dialog groups your defined configurations by template type, and allows you to edit configuration templates at the bottom. You can edit the selected configuration in the right panel. Resize the dialog to see any hidden items.
In this dialog, you can:
You can define new run/debug configurations from the Run/Debug Configurations dialog, the Project window, or the Code Editor. The new configuration must be based on a configuration template.
The Run/Debug Configurations dialog displays your run/debug configurations and the available configuration templates. You can start a new configuration directly from a template, or from a copy of another configuration. You can then change the field values as needed.
Alternatively, you can right-click an item in the Project window to automatically create a configuration specific to that item. For example, if you want to run a particular activity, you can right-click the activity Java file and select Run. Depending on the item, Android Studio uses an Android App, Android Instrumented Tests, or JUnit configuration template to create the configuration.
In the Code Editor, you can easily create a test and run/debug configuration for a class or method, and then execute it.
When you create a configuration outside of the Run/Debug Configurations dialog, the configuration is temporary unless you save it. By default, you can have up to five temporary configurations in the project before Android Studio starts to remove them. To change this default, open Android Studio settings, and change Advanced Settings > Run/Debug > Temporary configurations limit. For more information about temporary configurations, see Creating and Saving Temporary Run/Debug Configurations.
To define a run/debug configuration based on a template, follow these steps:
.
Be sure to correct any errors displayed at the bottom of the dialog.
To define a run/debug configuration starting from a copy of another configuration, follow these steps:
.
Be sure to correct any errors displayed at the bottom of the dialog.
Android Studio can create a run/debug configuration for some items displayed in the Project window. The configuration is based on a configuration template, as follows:
To create a run/debug configuration for an item in your project, follow these steps:
Figure 2. Save the configuration
Note: If you right-click and run or debug the same item (but not an activity), Android Studio creates a new configuration.
Android Studio lets you define a test run configuration for a class or method, and then execute it. For example, if you create a new class, you can create and run a test for it. If the test passes, you can then run the tests for the rest of the project to make sure that your new code doesn't break anything somewhere else.
Android Studio uses the Android Instrumented Tests or Android JUnit template, depending on your source set. For a local unit test, you can optionally run with code coverage.
To create a run/debug configuration for a class or method in your Java code, follow these steps:
The new test appears in the Project window in the corresponding test source set.
Figure 3. Save the configuration
If you've saved a run/debug configuration, you can select it before you run or debug your app.
To use a saved run/debug configuration, follow these steps:
The drop-down list is to the left of Run
and Debug
;
for example, 
.
Alternatively, click Run or
Debug
.
To edit a run/debug configuration, follow these steps:
Be sure to correct any errors displayed at the bottom of the dialog.
You can edit the configuration templates provided by Android Studio to suit your development process. When you edit a template, it doesn't affect existing configurations that use the template. So, for example, if you need to create a number of configurations of a certain type, you can edit the template and then change it back when you're done.
Although you can't create new templates, you can create configurations to use similar to a template. You can copy a configuration and edit the copy to create new configurations.
To edit a template, follow these steps:
Be sure to correct any errors displayed at the bottom of the dialog.
In the Run/Debug Configurations dialog, you can order your configurations to find them quickly. You can sort the items in the folder alphabetically, and create new folders to group configurations.
To sort configurations alphabetically, follow these steps:
.
To group configurations in folders, follow these steps:
.
You can specify tasks to execute before applying the run/debug configuration. The tasks are performed in the order they appear in the list.
Note: Defining before launch tasks is an advanced feature. Instead of
using this feature, we recommend that you put any preparation logic as tasks in your
build.gradle file so they'll be executed when you build from the command line.
To create a task list, follow these steps:
and select a task type. If a dialog opens, fill in the fields and
click OK.
and Down
to move it up or down in the list.This option is deselected by default.
This option is selected by default.
To remove a task from the list, follow these steps:
.To edit a task, follow these steps:
.
The following table lists the available tasks you can add.
| Task | Description |
|---|---|
| Run External tool | Run an application that's external to Android Studio. In the External Tools dialog, select one or more applications that you want to run and then click OK. If the application isn't defined in Android Studio yet, add its definition in the Create Tools dialog. For more information, see Configuring Third-Party Tools and External Tools. |
| Run Another Configuration | Execute one of the existing run/debug configurations. In the Choose Configuration to Execute dialog, select a configuration to execute and then click OK. |
| Make | Compile the project or the module. Android Studio executes the Make Module command if the run/debug configuration specifies a particular module, or it executes the Make Project command if no modules are specified. |
| Make Project | Compile the project. Android Studio executes the Make Project command. |
| Make, no error check | This option is the same as Make, except that Android Studio executes the run/debug configuration irrespective of the compilation result. |
| Build Artifacts | Unsupported in Android Studio. |
| Run Gradle task | Run a Gradle task. In the dialog that opens, specify the details and then click OK. For more information, see Gradle. |
| Gradle-aware Make | Compile the project and run Gradle. |
| App Engine Gradle builder | The App Engine Gradle builder task syncs the project and then builds the module. |
Android Studio provides configuration templates to help you get started quickly. The following sections describe the templates that apply to Android development with Android Studio:
Note: Android Studio 2.1.x and lower had a Native Application template, which newer versions don't have. If you have a Native Application template in a project, Android Studio converts it to Android App when you load the project. A Convert Project dialog guides you through the process.
The following unsupported templates come from IntelliJ IDEA and aren't specific to Android development with Android Studio. For information about using these templates, follow the links to the IntelliJ IDEA documentation.
The Name, Allow parallel run, and Store as project file options are common to multiple configuration templates. To learn more about them, see Common settings.
Android Studio stores the shared run/debug configuration in individual XML
files under the project_directory/.idea/runConfigurations/ folder.
For more information, see
Directory-based format in the IntelliJ projects documentation.
You can run or debug Android apps and activities on virtual or hardware devices by using configurations based on this template.
In the General tab, you can specify installation, launch, and deployment options. The Miscellaneous tab also contains installation options.
Note: If you want to test downloading and installing feature modules on demand, you must do so after you publish your app bundle and then use the Play Console internal test track. To learn more, read Upload your app bundle to the Play Console.
pm
install options you want to use. Format the options the same way that you would on
the command line, but without a path. Here are some examples:
-i foo.bar.baz -r /path/to/apk
and
-d -r
<intent-filter> <action android:name="android.intent.action.MAIN" /> <category android:name="android.intent.category.LAUNCHER" /> </intent-filter>
am
start options you want to use. Format the options the same way that you would on the
command line, but without an intent. For example:
-W
This option doesn't appear if you chose a Launch value of Nothing.
Default: no options.Deployment Target Options: Use same device for future launches
,
and then start it again. The Select Deployment dialog will display so you can select
a device.
In the Miscellaneous tab, you can specify logcat, installation, launch, and deployment options. The General tab also contains installation options.
If selected, when Android Studio detects that it doesn't have to reinstall an APK because it hasn't changed, it will force-stop the app so that the app starts from the default launcher activity. If this option is deselected, Android Studio doesn't force-stop the app.
This option works with the previous option that controls whether an APK is installed or not. For both Installation Options fields, leave them at the default unless you explicitly want to force an install every time.
In some cases you might want to deselect this option. For example, if you're writing an input method editor (IME), force-stopping the app deselects it as the current keyboard, which you might not want.
Default: selected
Specify debug options in the Debugger tab.
For C and C++ code, Android Studio uses the LLDB debugger. In addition to the normal Android Studio UI, the debugger window has an LLDB tab that lets you enter LLDB commands during debugging. You can enter the same commands that Android Studio uses to display information in the debugger UI, and you can perform additional operations.
For C and C++ projects, you can add symbol directories, as well as LLDB startup and post attach commands, in the Debugger tab. To do so, you use buttons similar to the following:
- Add a directory or command.
- Select a directory or command, and then click this button to remove the item.
- Select a directory or command, and then click this button to move the item up in
the list.
- Select a directory or command, and then click this button to move the item down in
the list.See Debug Your App for more information about debugging in Android Studio.
| Field | Description |
|---|---|
| Debug type | Select one of the following options:
The Detect Automatically option is recommended because it chooses the right debug type for your project. |
| Symbol Directories | If you want to add symbol files to provide the debugger with C or C++ information generated outside of Android Studio, you can add one or more directories here. Android Studio preferentially uses any files within these directories over files generated by the Android Plugin for Gradle. The debugger searches the directories from top to bottom, in order, until it finds what it needs. It searches recursively through the files in the directory. To optimize the list and save time, put the directories used most often toward the top of the list. If you specify a directory high in the tree, it can take longer to search all of the subdirectories. If you add a very specific directory, it takes less time to search. You need to find the right balance between speed and finding the files you need for debugging. For example, if you have a directory that contains subdirectories for different Android Binary Interfaces (ABIs), you can choose to add a directory for a specific ABI or for all ABIs. Although it can take longer to search through the upper-level directory, it's also more foolproof if you decide to debug on a different device. Note that you don't have to add directories containing Gradle symbol files because the debugger uses them automatically. |
| LLDB Startup Commands | Add LLDB commands that you want to execute before the debugger attaches to the process. For example, you can define settings for the environment, as shown in the following command:
LLDB executes the commands in order from top to bottom. |
| LLDB Post Attach Commands | Add LLDB commands that you want to execute right after the debugger attaches to the process. For example:
LLDB executes the commands in order from top to bottom. |
| Host working directory | Specify the LLDB working directory. |
| Logging: Target channels | Specify LLDB log options. Android Studio sets the default options based on the team's experience — so it's not too slow but contains needed information for troubleshooting issues. The log is often requested for Android Studio bug reports. This default is
You can change the default to gather more information. For example, the
following log options gather information about a specific
lldb process
platform:gdb-remote packets
For a complete list of log
commands, enter the
Android Studio places device logs in the following location, where
Or, if
multiple users access a device, it places the logs in the following location,
where
For information about using LLDB for remote debugging, see Remote Debugging. |
| Before Launch | See Defining Before Launch Operations. |
The Enable advanced profiling option must be checked to enable certain features in the Android Profiler when your device is running Android 7.1 or lower.
The test template that you should use depends on your source set. The Android Instrumented Tests template is for an instrumented test. The Android JUnit template is for a local unit test.
Note: If you're using Firebase Test Lab to test on a variety of devices, you can use the Android JUnit template to define your instrumented tests. For more information, see Run Your Tests with Firebase Test Lab.
The following tab descriptions cover the tabs and fields for the Android Instrumented test template. For information about the tabs and fields for the Android JUnit test template, see the IntelliJ Run/Debug Configuration: JUnit page.
In General tab, you can specify test location, instrumentation runner, adb shell, and deployment options.
build.gradle file specifies the location of the instrumentation
runner; this value overrides it. The default is typically the AndroidJUnitRunner
class from AndroidX Test.
Type any adb am
instrument options you want to use. Don't type the component. For example,
if you're using
AndroidJUnitRunner
from AndroidX Test, you can use this
field to pass additional options to the runner, such as -e size
small.
Default: no options
Select an option:
The Miscellaneous tab contains logcat and installation options.
If selected, when Android Studio detects that it doesn't have to reinstall an APK because it hasn't changed, it will force-stop the app so that the app starts from the default launcher activity. If this option is deselected, Android Studio doesn't force-stop the app.
This option works in conjunction with the previous option that controls whether an APK is installed or not. For both Installation Options fields, leave them at the default unless you explicitly want to force an install every time.
In some cases you might want to deselect this option. For example, if you're writing an input method editor (IME), force-stopping the app deselects it as the current keyboard, which you might not want.
Default: selected
Specify debug options in the Debugger tab.
For C and C++ code, Android Studio uses the LLDB debugger. In addition to the normal Android Studio UI, the debugger window has an LLDB tab that lets you enter LLDB commands during debugging. You can enter the same commands that Android Studio uses to display information in the debugger UI, and you can perform additional operations.
For C and C++ projects, you can add symbol directories, as well as LLDB startup and post attach commands, in the Debugger tab. To do so, you use buttons similar to the following:
- Add a directory or command.
- Select a directory or command, and then click this button to remove the item.
- Select a directory or command, and then click this button to move the item up in
the list.
- Select a directory or command, and then click this button to move the item down in
the list.See Debug Your App for more information about debugging in Android Studio.
| Field | Description |
|---|---|
| Debug type | Select one of the following options:
The Detect Automatically option is recommended because it chooses the right debug type for your project. |
| Symbol Directories | If you want to add symbol files to provide the debugger with C or C++ information generated outside of Android Studio, you can add one or more directories here. Android Studio preferentially uses any files within these directories over files generated by the Android Plugin for Gradle. The debugger searches the directories from top to bottom, in order, until it finds what it needs. It searches recursively through the files in the directory. To optimize the list and save time, put the directories used most often toward the top of the list. If you specify a directory high in the tree, it can take longer to search all of the subdirectories. If you add a very specific directory, it takes less time to search. You need to find the right balance between speed and finding the files you need for debugging. For example, if you have a directory that contains subdirectories for different Android Binary Interfaces (ABIs), you can choose to add a directory for a specific ABI or for all ABIs. Although it can take longer to search through the upper-level directory, it's also more foolproof if you decide to debug on a different device. Note that you don't have to add directories containing Gradle symbol files because the debugger uses them automatically. |
| LLDB Startup Commands | Add LLDB commands that you want to execute before the debugger attaches to the process. For example, you can define settings for the environment, as shown in the following command:
LLDB executes the commands in order from top to bottom. |
| LLDB Post Attach Commands | Add LLDB commands that you want to execute right after the debugger attaches to the process. For example:
LLDB executes the commands in order from top to bottom. |
| Host working directory | Specify the LLDB working directory. |
| Logging: Target channels | Specify LLDB log options. Android Studio sets the default options based on the team's experience — so it's not too slow but contains needed information for troubleshooting issues. The log is often requested for Android Studio bug reports. This default is
You can change the default to gather more information. For example, the
following log options gather information about a specific
lldb process
platform:gdb-remote packets
For a complete list of log
commands, enter the
Android Studio places device logs in the following location, where
Or, if
multiple users access a device, it places the logs in the following location,
where
For information about using LLDB for remote debugging, see Remote Debugging. |
| Before Launch | See Defining Before Launch Operations. |
This run/debug configuration applies to the Google Cloud Platform. When you follow these steps and
sync your project to the build.gradle file, Android Studio creates
an App Engine DevAppServer configuration for you.
Note that the IntellJ IDEA App Engine Server template is a different template that's not available in Android Studio.
build.gradle
file, the App Engine DevAppServer configuration fields are filled in for you (recommended).
Selecting File > Sync Project with Gradle Files also syncs the project. Default: selected
Specify the command-line options you want to pass to the VM for launching the DevAppServer. When specifying the options:
" ").
\").
For more information about VM options, see the documentation for your J2SE
version, such as
java JDK 7
and java JDK 8.
Default: no options
The Wear OS Complication, Tile, and Watch Face templates let you run or debug Wear OS apps on virtual or hardware devices. Most of the template configuration options are the same as the Android App options. Here are the options that are more specific to the Wear OS run/debug configurations:
Alternatively, you can also run these surfaces from the gutter icon that is located next to the declaration of the surface, as shown in the following image. If an error occurs, such as "Error while setting the tile," check that you've correctly configured the surface, including declaring the surface in your manifest.
Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
Last updated 2026-06-02 UTC.