Skip to content

Most visited

Recently visited


Create an Android Library

An Android library is structurally the same as an Android app module. It can include everything needed to build an app, including source code, resource files, and an Android manifest. However, instead of compiling into an APK that runs on a device, an Android library compiles into an Android Archive (AAR) file that you can use as a dependency for an Android app module. Unlike JAR files, AAR files can contain Android resources and a manifest file, which allows you to bundle in shared resources like layouts and drawables in addition to Java classes and methods.

A library module is useful in the following situations:

In either case, simply move the files you want to reuse into a library module then add the library as a dependency for each app module. This page teaches you how to do both.

Create a library module

To create a new library module in your project, proceed as follows:

  1. Click File > New > New Module.
  2. In the Create New Module window that appears, click Android Library, then click Next.

    There's also an option to create a Java Library, which builds a traditional JAR file. While a JAR file is useful for many projects—especially when you want to share code with other platforms—it does not allow you to include Android resources or manifest files, which is very useful for code reuse in Android projects. So this guide focuses on creating Android libraries.

  3. Give your library a name and select a minimum SDK version for the code in the library, then click Finish.

Once the Gradle project sync completes, the library module appears in the Project panel on the left. If you don't see the new module folder, make sure it's displaying the Android view.

Convert an app module to a library module

If you have an existing app module with all the code you want to reuse, you can turn it into a library module as follows:

  1. Open the module-level build.gradle file.
  2. Delete the line for the applicationId. Only an Android app module can define this.
  3. At the top of the file, you should see the following:
    apply plugin: ''

    Change it to the following:

    apply plugin: ''
  4. Save the file and click File > Sync Project with Gradle Files.

That's it. The entire structure of the module remains the same, but it now operates as an Android library and the build will now create an AAR file instead of an APK.

When you want to build the AAR file, select the library module in the Project window and then click Build > Build APK.

Add your library as a dependency

To use your Android library's code in another app module, proceed as follows:

  1. Add the library to your project in either of the following ways (if you created the library module within the same project, then it's already there and you can skip this step):
    • Add the compiled AAR (or JAR) file (the library must be already built):
      1. Click File > New > New Module.
      2. Click Import .JAR/.AAR Package then click Next.
      3. Enter the location of the compiled AAR or JAR file then click Finish.
    • Import the library module to your project (the library source becomes part of your project):
      1. Click File > New > Import Module.
      2. Enter the location of the library module directory then click Finish.

      The library module is copied to your project, so you can actually edit the library code. If you want to maintain a single version of the library code, then this is probably not what you want and you should instead add the compiled AAR file as described above.

  2. Make sure the library is listed at the top of your settings.gradle file, as shown here for a library named "my-library-module":
    include ':app', ':my-library-module'
  3. Open the app module's build.gradle file and add a new line to the dependencies block as shown in the following snippet:
    dependencies {
        compile project(":my-library-module")
  4. Click Sync Project with Gradle Files.

In this example above, the compile configuration adds the library named my-library-module as a build dependency for the entire app module. If you instead want the library only for a specific build variant, then instead of compile, use buildVariantNameCompile. For example, if you want to include the library only in your "pro" product flavor, it looks like this:

productFlavors {
    pro { ... }
dependencies {
    proCompile project(":my-library-module")

Any code and resources in the Android library is now accessible to your app module, and the library AAR file is bundled into your APK at build time.

However, if you want to share your AAR file separately, you can find it in project-name/module-name/build/outputs/aar/ and you can regenerate it by clicking Build > Make Project.

Publish non-default variants of your library

If you're using Android plugin for Gradle 3.0.0 or higher, the plugin automatically publishes all versions of your local library module dependencies and matches each of them with the corresponding version of your app. So, instead of following the instructions described in this section, read Use variant-aware dependency management.

By default, the library module publishes and exposes only the "release" build variant to other Android projects and modules. That is, if an app module consumes the library as a dependency, Gradle targets only the "release" variant of the library even when it's building a debug version of the app. However, you can tell Gradle to target the "debug" build variant by adding the following to the library's build.gradle file:

android {
  // Sets the "debug" build variant as the default variant
  // of the library that Gradle should publish.
  defaultPublishConfig "debug"

Now Gradle always publishes the "debug" variant of the library to other modules. However, if the library module uses product flavors, you must configure the defaultPublishConfig property and specify a build variant by its full configuration name (otherwise, Gradle doesn't publish your library because the traditional "release" and "debug" variants no longer exist). The following sample targets a build variant that combines the "demo" product flavor and "debug" build type:

android {
  defaultPublishConfig "demoDebug"

Keep in mind, if you are building a release version of your app for publication, you need to change defaultPublishConfig to use a release variant of the library. Alternatively, you can tell Gradle to publish and expose all available variants of the library and configure each app variant to use only the one it needs. To tell Gradle to publish all variants of the library, include the following line in the library's build.gradle file:

android {
  // Tells Gradle to build all variants of the library. Note that this
  // may increase build times because Gradle must build multiple AARs,
  // instead of only one.
  publishNonDefault true

Note: When publishing all variants of your library to Maven, the Maven publishing plugin publishes the default variant of the library with each additional variant as an additional artifact. Gradle differentiates each of those artifacts by setting its classifier to the variant name, such as "debug". However, this behavior is not fully supported by the Android plugin for Gradle, and you should either publish a single variant of the library to Maven, or set publishNonDefault to true only when publishing different variants of your library to local Android modules or projects.

Now you can configure the dependencies block in the app's build.gradle file to target any of the available variants of the library. The following code snippet in the app module's build.gradle file instructs Gradle to use the library's "demoDebug" variant when building the "demoDebug" version of the app and to use the library's "fullRelease" variant when building the "fullRelease" version of the app:

android {...}

// Creates Gradle dependency configurations to use in the dependencies block.
configurations {
  // Initializes placeholder configurations that the Android plugin can use when targeting
  // the corresponding variant of the app.
  demoDebugCompile {}
  fullReleaseCompile {}

dependencies {
  // If the library configures multiple build variants using product flavors,
  // you must target one of the library's variants using its full configuration name.
  demoDebugCompile project(path: ':my-library-module', configuration: 'demoDebug')
  fullReleaseCompile project(path: ':my-library-module', configuration: 'fullRelease')

Choose resources to make public

All resources in a library default to public. To make all resources implicitly private, you must define at least one specific attribute as public. Resources include all files in your project’s res/ directory, such as images. To prevent users of your library from accessing resources intended only for internal use, you should use this automatic private designation mechanism by declaring one or more public resources. Alternately, you can make all resources private by adding an empty <public /> tag , which marks nothing as public, which makes everything else (all resources) private.

To declare a public resource, add a <public> declaration to your library’s public.xml file. If you haven’t added public resources before, you need to create the public.xml file in the res/values/ directory of your library.

The following example code creates two public string resources with the names mylib_app_name and mylib_public_string:

    <public name="mylib_app_name" type="string"/>
    <public name="mylib_public_string" type="string"/>

You should make public any resources that you want to remain visible to developers using your library. For example, although most of the resources in the v7 appcompat library are private, attributes controlling the Toolbar widget are public to support material design.

Implicitly making attributes private not only prevents users of your library from experiencing code completion suggestions from internal library resources but also allows you to rename or remove private resources without breaking clients of your library. Private resources are filtered out of code completion and the theme editor, and Lint warns you when you try to reference a private resource.

When building a library, the Android Gradle plugin gets the public resource definitions and extracts them into the public.txt file, which is then packaged inside the AAR file.

Development considerations

As you develop your library modules and dependent apps, be aware of the following behaviors and limitations.

Once you have added references to library modules to your Android app module, you can set their relative priority. At build time, the libraries are merged with the app one at a time, starting from the lowest priority to the highest.

Anatomy of an AAR file

The file extension for an AAR file is .aar, and the Maven artifact type should be aar as well. The file itself is a zip file containing the following mandatory entries:

Additionally, an AAR file may include one or more of the following optional entries:

This site uses cookies to store your preferences for site-specific language and display options.

Get the latest Android developer news and tips that will help you find success on Google Play.

* Required Fields


Follow Google Developers on WeChat

Browse this site in ?

You requested a page in , but your language preference for this site is .

Would you like to change your language preference and browse this site in ? If you want to change your language preference later, use the language menu at the bottom of each page.

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.

Take a short survey?
Help us improve the Android developer experience. (April 2018 — Developer Survey)