Gradle for Android

Gradle is an Android build system which automates a number of build processes. This automation means that many common build errors are less likely to occur. Most notably in Unity, it reduces the method reference count in DEX (Dalvik Executable format) files, meaning that you are less likely to come across DEX limit problems. However, due to the differences between Gradle and the default Unity Android build system, some existing projects may be hard to convert to Gradle.

You can either build the output package (APK) using the Gradle build system in Unity, or export the Gradle project and build it in an external tool (such as Android Studio).

To learn more, see Gradle’s resources on Getting Started with Gradle for Android Build.

Building with Gradle for Android

To build your Android build with Gradle in Unity:

In the Unity Editor, open the Build Settings window (menu: File > Build Settings…)
In the Platform list, select Android
Set the Build System drop-down to Gradle (new), then click Build

Exporting the Gradle project

To export a Gradle project, follow the instructions above, but tick the Export Project option in the Build window before you click Build. When you click Build Unity generates a Gradle project in the specified directory rather than building the APK. Import this project into Android Studio to make additional modifications or to get full control of the build process.

See Android Studio’s documentation on configuring your build for more information about building an output package (APK).

Providing a custom build.gradle template

To use your own build.gradle file when building the APK from Unity, import your build.gradle file to Assets/Plugins/Android/mainTemplate.gradle. Note that the file might use some template variables like TARGETSDKVERSION. See the default mainTemplate.gradle file in the Unity installation for an example file.

Errors when building with Gradle

If an error occurs during building for Android using Gradle, Unity displays an error dialog box. Click Troubleshoot to open the Gradle troubleshooting Unity documentation in your system’s browser.