Add build dependencies

The Gradle build system in Android Studio makes it easy to 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 plugin for Gradle. For a deeper conceptual guide to Gradle dependencies, you should also see the Gradle guide for dependency management—but remember that your Android project must use only the dependency configurations defined on this page.

Dependency types

To add a dependency to your project, specify a dependency configuration such as implementation in the dependencies block of your build.gradle file.

For example, the following build.gradle file for an app module includes three different types of dependencies:

Groovy

apply plugin: 'com.android.application'

android { ... }

dependencies {
    // Dependency on a local library module
    implementation project(":mylibrary")

    // Dependency on local binaries
    implementation fileTree(dir: 'libs', include: ['*.jar'])

    // Dependency on a remote binary
    implementation 'com.example.android:app-magic:12.3'
}

Kotlin

plugins {
    id("com.android.application")
}

android { ... }

dependencies {
    // Dependency on a local library module
    implementation(project(":mylibrary"))

    // Dependency on local binaries
    implementation(fileTree(mapOf("dir" to "libs", "include" to listOf("*.jar"))))

    // Dependency on a remote binary
    implementation("com.example.android:app-magic:12.3")
}

Each of these requests a different kind of library dependency as follows:

Local library module dependency

Groovy

dependencies {
    // Adds libraries defining annotations to only the compile classpath.
    compileOnly 'com.google.dagger:dagger:version-number'
    // Adds the annotation processor dependency to the annotation processor classpath.
    annotationProcessor 'com.google.dagger:dagger-compiler:version-number'
}

Kotlin

implementation(project(":mylibrary"))

Groovy

implementation project(':mylibrary')

This declares a dependency on an Android library module named "mylibrary" (this name must match the library name defined with an include: in your settings.gradle file). When you build your app, the build system compiles the library module and packages the resulting compiled contents in the APK.

Local binary dependency

Groovy

  implementation fileTree(dir: 'libs', include: ['*.jar'])
  

Kotlin

  implementation fileTree(dir: 'libs', include: ['*.jar'])
  

Gradle declares dependencies on JAR files inside your project's module_name/libs/ directory (because Gradle reads paths relative to the build.gradle file).

Alternatively, you can specify individual files as follows:

Groovy

  implementation files('libs/foo.jar', 'libs/bar.jar')
  

Kotlin

  implementation files('libs/foo.jar', 'libs/bar.jar')
  
Remote binary dependency

Groovy

  implementation 'com.example.android:app-magic:12.3'
  

Kotlin

  implementation 'com.example.android:app-magic:12.3'
  

This is actually shorthand for the following:

Groovy

  implementation group: 'com.example.android', name: 'app-magic', version: '12.3'

Kotlin

  implementation group: 'com.example.android', name: 'app-magic', version: '12.3'

This declares a dependency on version 12.3 of the "app-magic" library, inside the "com.example.android" namespace group.

Note: Remote dependencies like this require that you declare the appropriate remote repositories where Gradle should look for the library. If the library does not already exist locally, Gradle pulls it from the remote site when the build requires it (such as when you click Sync Project with Gradle Files or when you run a build).

Native dependencies

As of Android Gradle Plugin 4.0, native dependencies can also be imported in the manner described in this document.

Depending on an AAR that exposes native libraries will automatically make them available to the build system used by externalNativeBuild. To access the libraries from your code, you must link to them in your native build scripts. For more information, see Using native dependencies.

Dependency configurations

Inside the dependencies block, you can declare a library dependency using one of several different dependency configurations (such as implementation shown above). 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. The table also compares these configurations to those that were deprecated as of Android Gradle Plugin 3.0.0.

Configuration Behavior
implementation Gradle adds the dependency to the compile classpath and packages the dependency to the build output. However, when your module configures an implementation dependency, it's letting Gradle know that you do not want the module to leak the dependency to other modules at compile time. That is, the dependency is available to other modules only at runtime.

Using this dependency configuration instead of api or compile (deprecated) 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.

This configuration behaves just like compile (which is now deprecated), but you should use it with caution and only with dependencies that you need to transitively export to other upstream consumers. That's because, if an api dependency changes its external API, Gradle recompiles all modules that have access to that dependency at compile time. So, 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 is 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.

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 APK by not adding transient dependencies that aren't critical. This configuration behaves just like provided (which is now deprecated).

Note: You can't use the compileOnly configuration with AAR dependencies.

runtimeOnly Gradle adds the dependency to the build output only, for use during runtime. That is, it is not added to the compile classpath. This configuration behaves just like apk (which is now deprecated).
annotationProcessor

To add a dependency on a library that is an annotation processor, you must add it to the annotation processor classpath using the annotationProcessor configuration. That's because using this configuration 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.

Note: Kotlin projects should use kapt to declare annotation processor dependencies.

lintChecks Use this configuration to include lint checks you want Gradle to execute when building your project.

Note: When using Android Gradle plugin 3.4.0 and higher, this dependency configuration no longer packages the lint checks in your Android Library projects. To include lint check dependencies in your AAR libraries, use the lintPublish configuration described below.

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.
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')
}

Deprecated Gradle configurations (available in AGP 1.0–4.2)

Configuration Behavior
apk Gradle adds the dependency to the build output only, for use during runtime. That is, it is not added to the compile classpath.
compile Gradle adds the dependency to the compile classpath and build output. Exports the dependency to other modules.
provided Gradle adds the dependency to the compile classpath only (that is, it is not added to the build output).

All of the above 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 an implementation dependency only to your "free" product flavor (using a remote binary dependency), it looks like this:

dependencies {
    freeImplementation 'com.google.firebase:firebase-ads:9.8.0'
}

However, if you want to add a dependency for a variant that combines a product flavor and a build type, then you must initialize the configuration name in the configurations block. The following sample adds a runtimeOnly dependency to your "freeDebug" build variant (using a local binary dependency).

configurations {
    // Initializes a placeholder for the freeDebugRuntimeOnly dependency
    // configuration.
    freeDebugRuntimeOnly {}
}

dependencies {
    freeDebugRuntimeOnly fileTree(dir: 'libs', include: ['*.jar'])
}

To add implementation dependencies for your local tests and instrumented tests , it looks like this:

dependencies {
    // Adds a remote binary dependency only for local tests.
    testImplementation 'junit:junit:4.12'

    // Adds a remote binary dependency only for the instrumented test APK.
    androidTestImplementation 'androidx.test.espresso:espresso-core:3.0.2'
}

However, certain configurations don't make sense in this situation. For example, because other modules can't depend on androidTest, you get the following warning if you use the androidTestApi configuration:

WARNING: Configuration 'androidTestApi' is obsolete and has been replaced with
'androidTestImplementation'.

Add annotation processors

If you add annotation processors to your compile classpath, you'll see an error message similar to the following:

Error: Annotation processors must be explicitly declared now.

To resolve this error, add annotation processors to your project by configuring your dependency using annotationProcessor as shown below: