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.

Note: In this table, when the name of a file looks like build.gradle(.kts), this means the file has a different name when the build files are written in Kotlin versus Groovy. The Kotlin version of the file ends with .kts (Kotlin file); the Groovy version omits it.

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.