Add build dependencies

The Gradle build system in Android Studio lets you include external binaries or other library modules to your build as dependencies. The dependencies can be located on your machine or in a remote repository, and any transitive dependencies they declare are automatically included as well. This page describes how to use dependencies with your Android project, including details about behaviors and configurations that are specific to the Android Gradle plugin (AGP). For a deeper conceptual guide to Gradle dependencies, see the Gradle guide for dependency management, but remember that your Android project must use only the dependency configurations defined on this page.

Add a library or plugin dependency

The best way to add and manage build dependencies is to use version catalogs, the method new projects use by default. This section covers the most common types of configurations used for Android projects; refer to the Gradle documentation for more options. For an example of an app that uses version catalogs, see Now in Android. If you already have build dependencies set up without version catalogs and have a multi-module project, we recommend migrating.

For guidance on adding and managing native dependencies (not common), see Native dependencies.

In the following example, a remote binary dependency (the Jetpack Macrobenchmark library), local library module dependency (myLibrary), and a plugin dependency (the Android Gradle plugin) are added to the project. Here are the general steps to add these dependencies to your project:

Add an alias for the version of the dependency that you want in the [versions] section of the version catalog file, called libs.versions.toml (under the gradle directory in Project view or Gradle Scripts in Android view):
```
[versions]
agp = "8.3.0"
androidx-macro-benchmark = "1.2.2"
my-library = "1.4"

[libraries]
...

[plugins]
...
```
Aliases can include dashes or underscores. These aliases generate nested values you can reference in build scripts. The references start with the name of the catalog, the libs part of libs.versions.toml. When using a single version catalog, we recommend keeping the default value of "libs."
Add an alias for the dependency in the [libraries] (for remote binaries or local library modules) or [plugins] (for plugins) sections of the libs.versions.toml file.
```
[versions]
...

[libraries]
androidx-benchmark-macro = { group = "androidx.benchmark", name = "benchmark-macro-junit4", version.ref = "androidx-macro-benchmark" }
my-library = { group = "com.myapplication", name = "mylibrary", version.ref = "my-library" }

[plugins]
androidApplication = { id = "com.android.application", version.ref = "agp" }
```
Some libraries are available in a published Bill of Materials (BOM) that groups families of libraries and their versions. You can include a BOM in your version catalog and build files, and let it manage those versions for you. See Using the Bill of Materials for details.
Add a reference to dependency alias to the build script of the module(s) that require the dependency. Convert the alias' underscores and dashes to dots when you reference it from a build script. Our module-level build script would look like this:
Kotlin
plugins { alias(libs.plugins.androidApplication) } dependencies { implementation(libs.androidx.benchmark.macro) implementation(libs.my.library) }
Groovy
plugins { alias 'libs.plugins.androidApplication' } dependencies { implementation libs.androidx.benchmark.macro implementation libs.my.library }
Plugin references include plugins after the catalog name, and version references include versions after the catalog name (version references are uncommon; see Dependencies with same version numbers for examples of version references.) Library references don't include a libraries qualifier, so you can't use versions or plugins at the start of a library alias.

Configure dependencies

Inside the dependencies block, you can declare a library dependency using one of several different dependency configurations (such as implementation shown earlier). Each dependency configuration provides Gradle with different instructions about how to use the dependency. The following table describes each of the configurations you can use for a dependency in your Android project.

Configuration	Behavior
`implementation`	Gradle adds the dependency to the compile classpath and packages the dependency to the build output. When your module configures an `implementation` dependency, it's letting Gradle know that you don't want the module to leak the dependency to other modules at compile time. That is, the dependency isn't made available to other modules that depend on the current module. Using this dependency configuration instead of `api` can result in significant build time improvements because it reduces the number of modules that the build system needs to recompile. For example, if an `implementation` dependency changes its API, Gradle recompiles only that dependency and the modules that directly depend on it. Most app and test modules should use this configuration.
`api`	Gradle adds the dependency to the compile classpath and build output. When a module includes an `api` dependency, it's letting Gradle know that the module wants to transitively export that dependency to other modules, so that it's available to them at both runtime and compile time. Use this configuration with caution and only with dependencies that you need to transitively export to other upstream consumers. If an `api` dependency changes its external API, Gradle recompiles all modules that have access to that dependency at compile time. Having a large number of `api` dependencies can significantly increase build time. Unless you want to expose a dependency's API to a separate module, library modules should instead use `implementation` dependencies.
`compileOnly`	Gradle adds the dependency to the compile classpath only (that is, it's not added to the build output). This is useful when you're creating an Android module and you need the dependency during compilation, but it's optional to have it present at runtime. For example, if you depend on a library that only includes compile-time annotations—typically used to generate code but often not included in the build output—you could mark that library `compileOnly`. If you use this configuration, then your library module must include a runtime condition to check whether the dependency is available, and then gracefully change its behavior so it can still function if it's not provided. This helps reduce the size of the final app by not adding transient dependencies that aren't critical. Note: You can't use the `compileOnly` configuration with Android Archive (AAR) dependencies.
`runtimeOnly`	Gradle adds the dependency to the build output only, for use during runtime. That is, it isn't added to the compile classpath. This is rarely used on Android, but commonly used in server applications to provide logging implementations. For example, a library could use a logging API that doesn't include an implementation. Consumers of that library could add it as an `implementation` dependency and include a `runtimeOnly` dependency for the actual logging implementation to use.
`ksp kapt annotationProcessor`	These configurations supply libraries that process annotations and other symbols in your code before it is compiled. They typically validate your code or generate additional code, reducing the code you need to write. To add such a dependency, you must add it to the annotation processor classpath using the `ksp`, `kapt`, or `annotationProcessor` configurations. Using these configurations improves build performance by separating the compile classpath from the annotation processor classpath. If Gradle finds annotation processors on the compile classpath, it deactivates compile avoidance, which negatively impacts build time (Gradle 5.0 and higher ignore annotation processors found on the compile classpath). The Android Gradle plugin assumes a dependency is an annotation processor if its JAR file contains the following file: `META-INF/services/javax.annotation.processing.Processor` If the plugin detects an annotation processor that's on the compile classpath, it produces a build error. `ksp` is a Kotlin Symbol Processor, and is run by the Kotlin compiler. `kapt` and `apt` are separate tools that process annotations before Kotlin or Java compilers execute. When deciding which configuration to use, consider the following: If a processor is available as a Kotlin Symbol Processor, use it as a `ksp` dependency. See Migrate from kapt to ksp for details on using Kotlin Symbol Processors. If the processor isn't available as a Kotlin Symbol Processor: If your project includes Kotlin source (but can also include Java source), use `kapt` to include it. If your project only uses Java source, use `annotationProcessor` to include it. For more information about using annotation processors, see Add annotation processors.
`lintChecks`	Use this configuration to include a library containing lint checks you want Gradle to execute when building your Android app project. Note that AARs that contain a `lint.jar` file will automatically run checks defined in that `lint.jar` file; you don't need to add an explicit `lintChecks` dependency. This lets you define libraries and associated lint checks in a single dependency, ensuring that your checks are run when consumers use your library.
`lintPublish`	Use this configuration in Android library projects to include lint checks you want Gradle to compile into a `lint.jar` file and package in your AAR. This causes projects that consume your AAR to also apply those lint checks. If you were previously using the `lintChecks` dependency configuration to include lint checks in the published AAR, you need to migrate those dependencies to instead use the `lintPublish` configuration. Kotlin dependencies { // Executes lint checks from the ":checks" project at build time. lintChecks(project(":checks")) // Compiles lint checks from the ":checks-to-publish" into a // lint.jar file and publishes it to your Android library. lintPublish(project(":checks-to-publish")) } Groovy dependencies { // Executes lint checks from the ':checks' project at build time. lintChecks project(':checks') // Compiles lint checks from the ':checks-to-publish' into a // lint.jar file and publishes it to your Android library. lintPublish project(':checks-to-publish') }

Configure dependencies for a specific build variant

All of the preceding configurations apply dependencies to all build variants. If you instead want to declare a dependency for only a specific build variant source set or for a testing source set, you must capitalize the configuration name and prefix it with the name of the build variant or testing source set.

For example, to add a remote binary dependency only to your "free" product flavor using the implementation configuration, use this: