Android build structure

Android projects contain many build-related files and directory structures to organize your application source and resources. Before diving into the configuration details, we'll take a look at the overall structure and the basics of what belongs in each part.

This table lists typical files in an Android project. The descriptions of each file or directory include notes on what type of content belongs there. Best practices evolve over time, and these descriptions may not match a project you've inherited or downloaded from the internet.

When writing your build files, use a declarative approach; build logic and task definitions should only appear in plugins. By limiting build logic to plugins, build files become data declarations, which are more direct for understanding and editing. Future versions may include an alternative specification such as Declarative Gradle, which will prevent build logic in the files.

Folder/File

Use

.gradle/

Gradle project cache directory

Managed by Gradle and contains the downloaded Gradle distribution, project cache, and configuration files.

Don't change files in this directory!

.idea/

Android Studio project metadata

Don't change files in this directory!

build.gradle(.kts)

Root build file

Should only contain plugin declarations to set up a common plugin classpath across subprojects.

Other code should reside in the settings or nested-project-level build files.

gradle.properties

Gradle execution configuration

Contains Gradle properties, controlling Gradle build environment aspects such as heap size, caching and parallel execution.

Some temporary Android properties are defined here, to reduce changes to the AGP DSL as they're added and later removed.

gradlew (linux, Mac)

gradlew.bat (Windows)

Gradle wrapper file

Bootstraps your build by downloading a Gradle distribution and then forwarding commands to it. This lets you run builds without having to preinstall Gradle.

local.properties

Local machine configuration

Contains properties related to the local machine, such as the location of the Android SDK.

Exclude this file from source control!

settings.gradle(.kts)

Gradle build initialization

Contains global build information for Gradle initialization and project configuration, such as

  • project name
  • list of subprojects to include in this build
  • repository specifications to locate plugins and dependencies
  • external Version Catalog imports.

gradle/

↳ libs.versions.toml

Version Catalog

Defines variables for dependencies and plugins used inside your build. You specify which versions you want to use here, ensuring consistency across all subprojects in your project.

↳ wrapper/

↳ gradle‑wrapper.jar

Gradle bootstrapping executable

Downloads the specified Gradle distribution (if it doesn't exist), and runs it, passing along any arguments

↳ gradle‑wrapper.properties

Configuration for Gradle wrapper

Specifies where to download the Gradle distribution (including which version to use).

app/

Subproject directory

Subprojects (known as "modules" in Android Studio) can build applications or libraries and may depend on other subprojects or external dependencies.

app is the conventional name for a top-level application subproject (but is not the required name). Other subprojects have similar structures with different names.

Any directory can be a subproject, and must contain at least a build.gradle(.kts) file, and be included in the build using settings.gradle(.kts).

↳ build.gradle(.kts)

Subproject-level build file

Declares how to build this subproject. Each subproject requires a separate build file, and should contain

  • plugins used to build this subproject
  • configuration blocks required by plugins
  • dependencies (libraries and platforms) included when building this subproject

You shouldn't include build logic (such as Kotlin function definitions or conditions) or task declarations in your build files. Build logic and tasks should only be contained inside plugins.

↳ src/

Subproject source files

Groups source files (application code and resources) into source sets. The main source set contains source files that are common to all variants, while other source sets contain source files unique to a variant.

↳ main/

Main source set

Source code and resources that are common across all build variants. This source acts as the base for all builds, and other, more specific source sets add to or override this source.

↳ java/

↳ kotlin/

Kotlin and Java source code

The java directory can contain mixed Java and Kotlin source code. If this subproject contains only Kotlin code, you can rename this directory kotlin.

Android
is a Kotlin-first platform. Java source is supported, but new APIs target the Kotlin language. We recommend using Kotlin for all new code and major updates to existing code.

↳ res/

Android resource files

Contains application resources, such as XML files and images. All applications use some basic resources, such as launcher icons, but many of these resources, such as layouts and menus, are only used in view-based applications. Compose applications use String resources defined under this directory.

↳ AndroidManifest.xml

Android application metadata

Read by Android package manager to tell the system

  • components defined by your application
  • necessary permissions
  • device compatibility
  • Android platform restrictions

↳ androidTest/

Device test source set

Contains source for tests that will be run on an Android-powered device or emulator. These tests have access to a real Android environment, but execute more slowly than host tests.

All source files in the main source set are available for use by source under androidTest.

↳ test/

Host test source set

Contains source for tests that run locally in a JVM, as opposed to tests that run on a device. These tests are much faster to run than device tests. However, any system calls (including the lifecycles that run your application) must be mocked, faked, stubbed or otherwise simulated.

All source files in the main source set are available for use by source under test.

↳ proguard-rules.pro

R8 configuration rules

Defines rules to control application shrinking, optimization, and obfuscation. R8 removes unneeded code and resources, optimizes runtime performance and further minimizes your code by renaming identifiers.