Gradle is an Android build system that automates a number of build processes and prevents many common build errors. In Unity, Gradle reduces the method reference count in DEX (Dalvik Executable format) files, which means you are less likely to come across DEX limit problems.
Unity uses Gradle for all Android builds. You can either build the output package (.apk, .aab) in Unity, or export a Gradle project from Unity, and then build it with an external tool such as Android Studio.
Unity version | Gradle version |
---|---|
2020.3 starting from 2020.3.15f1 2021.1 starting from 2021.1.16f1 |
6.1.1 |
2020.1, 2020.2, 2020.3 up to and including 2020.3.14f1 2021.1 up to and including 2021.1.15f1 |
5.6.4 |
2019.4 | 5.1.1 |
To learn more about:
To build a Gradle project, follow these steps:
Select the:
To export your Unity Project as a Gradle project, enable the Export Project setting, and then select the Export button. When you do this, Unity generates a Gradle project in the folder you specify, and doesn’t build an .apk file. Import this project into Android Studio or another external tool to make further changes, or to build it from there.
Unity 2019.3 and newer versions create a Gradle project with two modules:
Gradle templates describe and configure how to build your Android app with Gradle. Each Gradle template represents a singleGradle project. Gradle projects can include, and depend on other Gradle projects.
A Gradle template consists of the following files:
File | Location | Contains |
---|---|---|
baseProjectTemplate.gradle |
In the exported project, root/build.gradle folder |
Contains configuration that is shared between all other templates/Gradle projects (repositories and the dependency on the Android Gradle plug-in). |
launcherTemplate.gradle_ |
In the exported project, root/launcher/build.gradle folder
|
Contains instructions on how to build the Android application (bundling, signing, APK splitting). It depends on the unityLibrary project and outputs either an .apk file or an app bundle. |
mainTemplate.gradle |
In the exported project, root/unityLibrary/build.gradle folder |
Contains instructions on how to build Unity as a Library. Outputs an .aar file. You can override the Unity template with a custom template in the Unity Editor. See the Providing a custom Gradle build template section on this page for more details. |
libTemplate.gradle |
Varies | Used if your Unity Project contains Android Library Projects as plug-insA set of code created outside of Unity that creates functionality in Unity. There are two kinds of plug-ins you can use in Unity: Managed plug-ins (managed .NET assemblies created with tools like Visual Studio) and Native plug-ins (platform-specific native code libraries). More info See in Glossary . |
You can provide a custom Gradle build template and select minification options in the Publishing Settings section of the Player SettingsSettings that let you set various player-specific options for the final game built by Unity. More info
See in Glossary window.
You can use a custom build.gradle
file for the unityLibrary module when you build the APK from Unity. This file contains specific build instructions specified in template variables. For a list of template variables, see the next section.
To use your own build.gradle
file for the unityLibrary module, follow these steps:
Unity then generates a default mainTemplate.gradle
file in your Project’s Assets/Plugins/Android/
folder. The path to the new file also appears under the Custom Main Gradle Template option in the Player Settings. Double-click the mainTemplate.gradle
file in the Project view to open it in an external text editor.
mainTemplate.gradle
file in the Project view for the unityLibrary moduleBy default, Unity uses the settingsTemplate.gradle
file from the Unity install directory to create the settings.gradle
file for your build. The settings.gradle
file contains project components which are involved in the build process. Unity creates the following components by default, which should always be included in the settings.gradle
file:
Additionally, if you add Android library plugins to your project, Unity automatically includes them in the settings file by replacing the **INCLUDES** entry.
If you want to add additional components to the settings.gradle
file that Unity doesn’t include by default, create a settingsTemplate.gradle
file in your project’s Assets/Plugins/Android/
folder. This overrides the default template.
If you use your own settingsTemplate.gradle
file, it must contain the following lines:
include ':launcher', ':unityLibrary'
**INCLUDES**
IPostGenerateGradleAndroidProject returns the path to the unityLibrary module. This keeps everything similar to versions earlier than Unity 2019.3 and doesn’t require any further changes, which means Unity can reach the app’s manifest and resources in a consistent way across versions.
The mainTemplate.gradle
file can contain the following variables:
Variable: | Description: |
---|---|
DEPS | List of project dependenciesIn the context of the Package Manager, a dependency is a specific package version (expressed in the form package_name@package_version ) that a project or another package requires in order to work. Projects and packages use the dependencies attribute in their manifests to define the set of packages they require. For projects, these are considered direct dependencies; for packages, these are indirect, or transitive, dependencies. More infoSee in Glossary; that is, the libraries that the Project uses. |
APIVERSION | API version to build for (for example, 25). |
MINSDKVERSION | Minimum API version (for example, 25). |
BUILDTOOLS | SDK Build tools used (for example, 25.0.1). |
TARGETSDKVERSION | API version to target (for example, 25). |
APPLICATIONID | Android Application ID (for example, com.mycompany.myapp). |
MINIFY_DEBUG | Enable minify for debug builds (true or false). |
PROGUARD_DEBUG | Use proguard for minification in debug builds (true or false.) |
MINIFY_RELEASE | Enable minify for release builds (true or false). |
PROGUARD_RELEASE | Use proguard for minification in release builds (true or false). |
USER_PROGUARD | Custom user proguard file (for example, proguard-user.txt ). |
SIGN | Complete the signingConfigs section if this build is signed. |
SIGNCONFIG | Set to signingConfig signingConfig.release if this build is signed. |
DIR_GRADLEPROJECT | The directory where Unity creates the Gradle project. |
DIR_UNITYPROJECT | The directory of your Unity Project. |
You can use Proguard minification to shrink and optimize your app. To activate this option, follow these steps:
Note: Proguard might strip out important code that your app needs, so use these options carefully.
To generate a custom proguard.txt
file, enable the User Proguard File setting in the Publishing Settings section of the Player Settings. This immediately generates the proguard.txt
file in your Project’s Assets/Plugins/Android/
folder.
To learn more about ProGuard, see the ProGuard manual.
If an error occurs when you use Gradle to build your app for Android, Unity displays an error dialog box. Select the Troubleshoot button to open the Gradle troubleshooting Unity documentation in your system’s browser.
When you visit any website, it may store or retrieve information on your browser, mostly in the form of cookies. This information might be about you, your preferences or your device and is mostly used to make the site work as you expect it to. The information does not usually directly identify you, but it can give you a more personalized web experience. Because we respect your right to privacy, you can choose not to allow some types of cookies. Click on the different category headings to find out more and change our default settings. However, blocking some types of cookies may impact your experience of the site and the services we are able to offer.
More information
These cookies enable the website to provide enhanced functionality and personalisation. They may be set by us or by third party providers whose services we have added to our pages. If you do not allow these cookies then some or all of these services may not function properly.
These cookies allow us to count visits and traffic sources so we can measure and improve the performance of our site. They help us to know which pages are the most and least popular and see how visitors move around the site. All information these cookies collect is aggregated and therefore anonymous. If you do not allow these cookies we will not know when you have visited our site, and will not be able to monitor its performance.
These cookies may be set through our site by our advertising partners. They may be used by those companies to build a profile of your interests and show you relevant adverts on other sites. They do not store directly personal information, but are based on uniquely identifying your browser and internet device. If you do not allow these cookies, you will experience less targeted advertising. Some 3rd party video providers do not allow video views without targeting cookies. If you are experiencing difficulty viewing a video, you will need to set your cookie preferences for targeting to yes if you wish to view videos from these providers. Unity does not control this.
These cookies are necessary for the website to function and cannot be switched off in our systems. They are usually only set in response to actions made by you which amount to a request for services, such as setting your privacy preferences, logging in or filling in forms. You can set your browser to block or alert you about these cookies, but some parts of the site will not then work. These cookies do not store any personally identifiable information.