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) |
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) |
Contains global build information for Gradle initialization and project configuration, such as
|
gradle/ |
|
↳ libs.versions.toml |
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/ |
Subprojects (known as "modules" in Android Studio) can build applications or libraries and may depend on other subprojects or external dependencies.
|
↳ build.gradle(.kts) |
Declares how to build this subproject. Each subproject requires a separate build file, and should contain
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/ |
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 |
↳ res/ |
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 |
Read by Android package manager to tell the system
|
↳ 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. |
↳ 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 |
↳ proguard-rules.pro |
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. |