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 compile 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:

apply plugin: 'com.android.application'

android { ... }
dependencies {
    // Dependency on a local library module
    compile project(":mylibrary")

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

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

Each of these request a different kind of dependency as follows:

Local library module dependency

compile project(':mylibrary')

This declares a dependency on an Android library module named "mylibrary" (this name must match the library name defined as an include in your settings.gradle file). It requires the build system to compile the library module with your app module and include the resulting AAR file in your APK.

Local binary dependency

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

Because Gradle reads paths relative to the build.gradle file, this tells the build system to add all JAR files inside your project's module_name/libs/ directory as dependencies.

Alternatively, you specify individual files as follows:

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

Remote binary dependency

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

This is actually shorthand for the following:

compile 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 "code.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).

Library dependency configurations

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

Note: Although the Java Plugin for Gradle offers dependency configurations that are similar to those defined below, you cannot use them in your Android projects—only the following configurations are compatible with the Android plugin for Gradle.

If you're using Android plugin for Gradle 3.0.0 or higher, you should use the new implementation, api, compileOnly, and runtimeOnly dependency configurations. They work similarly to the configurations described below, but they improve build speeds on multi-module projects by allowing you to restrict whether Gradle transitively exports a dependency to other modules. To learn more, read Use the new dependency configurations.

compile

Gradle adds the dependency to the compilation classpath and to the APK.

apk

Gradle adds the dependency to the APK only (it is not added to the compilation classpath).

Note: You can use apk only for JAR binary dependencies. It does not support library modules or AAR binary dependencies.

provided

Gradle adds the dependency to the compilation classpath only (it is not added to the APK). This is useful when you're creating an Android library module and you need the dependency during compilation, but it's optional to have present at runtime. That is, 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.

You might also use this in an Android app module when your dependency is a JAR file that you need at compile-time and that you can safely assume is already available at runtime (and therefore you don't want to copy it into your APK). Or perhaps you want to compile against the JAR specified with the provided configuration, but use the apk configuration to package a different JAR into the APK, which includes the same APIs you need at runtime.

Note: If you're creating an Android app module, you cannot use provided for AAR dependencies, only for JARs. In an Android library module, you can use it for both JARs and AARs.

The above configurations apply to your project's main source set, which is applied 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 compile dependency only to your "free" product flavor (using a remote binary dependency), it looks like this:

dependencies {
    freeCompile '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 an apk dependency to your "freeDebug" build variant (using a local binary dependency):

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

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

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

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

    // Adds a remote binary dependency only for the instrumented test APK.
    androidTestCompile 'com.android.support.test.espresso:espresso-core:3.0.2'
}

And if your library module provides multiple variants, you can add different library variants to different app variants like this:

dependencies {
  // Adds the 'debug' variant of the library to the debug variant of the app
  debugCompile project(path: ':my-library-module', configuration: 'debug')

  // Adds the 'release' variant of the library to the release variant of the app
  releaseCompile project(path: ':my-library-module', configuration: 'release')
}

If you're using Android plugin for Gradle 3.0.0 or higher, the plugin automatically matches each variant of your app with corresponding variants of its local library module dependencies for you. That is, you should no longer target specific variants of local module dependencies, as shown above. To learn more, read Use variant-aware dependency management.

For more information, see Java Plugin dependency management.

Remote repositories

When your dependency is something other than a local library or file tree, Gradle looks for the files in whichever online repositories are specified in the repositories block of your build.gradle file.

By default, new Android Studio projects declare JCenter as the repository location in the project's top-level build.gradle file, as shown here:

allprojects {
    repositories {
        jcenter()
    }
}

If you want something from the Maven central repository, then add mavenCentral(), or for a local repository use mavenLocal():

allprojects {
    repositories {
        jcenter()
        mavenCentral()
        mavenLocal()
    }
}

Or you can declare specific Maven or Ivy repositories as follows:

allprojects {
    repositories {
        maven {
            url "https://repo.example.com/maven2"
        }
        maven {
            url "file://local/repo/"
        }
        ivy {
            url "https://repo.example.com/ivy"
        }
    }
}

For more information, see the Gradle Repositories guide.

Google's Maven repository

The most recent versions of the following Android libraries are available from Google's Maven repository:

• Android Support Library
• Architecture Components Library
• Constraint Layout Library
• Android Test
• Databinding Library
• Android Instant App Library
• Wear OS
• Google Play services
• Firebase

You can see all available artifacts at Google's Maven repository index (see below for programmatic access).

To add one of these libraries to your build, include Google's Maven repository in your top-level build.gradle file:

allprojects {
    repositories {
        google()

        // If you're using a version of Gradle lower than 4.1, you must instead use:
        // maven {
        //     url 'https://maven.google.com'
        // }
        // An alternative URL is 'https://dl.google.com/dl/android/maven2/'
    }
}

Then add the desired library to your module's dependencies block. For example, the appcompat library looks like this:

dependencies {
    compile 'com.android.support:appcompat-v7:27.1.1'
}

However, if you're trying to use an older version of the above libraries and your dependency fails, then it's not available in the Maven repository and you must instead get the library from the offline repository.

Programmatic access

For programmatic access to Google's Maven artifacts, you can get an XML list of artifact groups from maven.google.com/master-index.xml. Then, for any group, you can view its library names and versions at:

maven.google.com/group_path/group-index.xml

For example, libraries in the android.arch.lifecycle group are listed at maven.google.com/android/arch/lifecycle/group-index.xml.

You can also download the POM and JAR files at:

maven.google.com/group_path/library/version/library-version.ext

For example: maven.google.com/android/arch/lifecycle/compiler/1.0.0/compiler-1.0.0.pom.

Offline repository from SDK Manager

For libraries not available from the Google Maven repository (usually older library versions), you must download the offline Google Repository package from the SDK Manager.

Then you can add these libraries to your dependencies block as usual.

The offline libraries are saved in android_sdk/extras/.

Dependency order

The order in which you list your dependencies indicates the priority for each: the first library is higher priority than the second, the second is higher priority than the third, and so on. This order is important in the event that resources are merged or manifest elements are merged into your app from the libraries.

For example, if your project declares the following:

• Dependency on LIB_A and LIB_B (in that order)
• And LIB_A depends on LIB_C and LIB_D (in that order)
• And LIB_B also depends on LIB_C

Then, the flat dependency order will be as follows:

1. LIB_A
2. LIB_D
3. LIB_B
4. LIB_C

This ensures that both LIB_A and LIB_B can override LIB_C; and LIB_D is still higher priority than LIB_B because LIB_A (which depends on it) has higher priority than LIB_B.

For more information about how manifests from different project sources/dependencies are merged, see Merge Multiple Manifest Files.

View the dependency tree

Some direct dependencies may have dependencies of their own. These are called transitive dependencies. Rather than requiring you to manually declare each transitive dependency, Gradle automatically gathers and adds them for you. To visualize both the direct and transitive dependencies of your project, the Android plugin for Gradle provides a Gradle task that generates a dependency tree for each build variant and testing source set.

To run the task, proceed as follows:

1. Select View > Tool Windows > Gradle (or click Gradle in the tool windows bar).
2. Expand AppName > Tasks > android and double-click androidDependencies. After Gradle executes the task, the Run window should open to display the output.

The following sample output shows the dependency tree for the debug build variant, and includes the local library module dependency and remote dependency from the previous example.

Executing tasks: [androidDependencies]
:app:androidDependencies
debug
/**
 * Both the library module dependency and remote binary dependency are listed
 * with their transitive dependencies.
 */
+--- MyApp:mylibrary:unspecified
|    \--- com.android.support:appcompat-v7:27.1.1
|         +--- com.android.support:animated-vector-drawable:27.1.1
|         |    \--- com.android.support:support-vector-drawable:27.1.1
|         |         \--- com.android.support:support-v4:27.1.1
|         |              \--- LOCAL: internal_impl-27.1.1.jar
|         +--- com.android.support:support-v4:27.1.1
|         |    \--- LOCAL: internal_impl-27.1.1.jar
|         \--- com.android.support:support-vector-drawable:27.1.1
|              \--- com.android.support:support-v4:27.1.1
|                   \--- LOCAL: internal_impl-27.1.1.jar
\--- com.android.support:appcompat-v7:27.1.1
     +--- com.android.support:animated-vector-drawable:27.1.1
     |    \--- com.android.support:support-vector-drawable:27.1.1
     |         \--- com.android.support:support-v4:27.1.1
     |              \--- LOCAL: internal_impl-27.1.1.jar
     +--- com.android.support:support-v4:27.1.1
     |    \--- LOCAL: internal_impl-27.1.1.jar
     \--- com.android.support:support-vector-drawable:27.1.1
          \--- com.android.support:support-v4:27.1.1
               \--- LOCAL: internal_impl-27.1.1.jar
...

For more information about managing dependencies in Gradle, see Dependency Management Basics in the Gradle User Guide.

Resolve duplicate class errors

When building your app, you get the following error if a class appears more than once on the runtime classpath:

Program type already present com.example.MyClass

This error typically occurs due to one of the following circumstances:

• A binary dependency includes a library that your app also includes as direct dependency. For example, your app declares a direct dependency on Library A and Library B, but Library A already includes Library B in its binary. To resolve this issue, remove Library B as a direct dependency.
• Your app has a local binary dependency and a remote binary dependency on the same library. To resolve this issue, you should remove one of the binary dependencies.

To help you determine which dependencies are contributing to the duplicate class error, inspect your app's dependency tree and look for dependencies that appear more than once.

If you can't easily identify the duplicate dependency, try using Android Studio's UI to search for dependencies that include the duplicate class as follows:

1. Select Navigate > Class from the menu bar.
2. In the pop-up search dialog, make sure that the box next to Include non-project items is checked.
3. Type the class that appeared in the build error.
4. Inspect the results for the dependencies that include the class.