Android keep rules explained: stop R8 from breaking your release build
R8 removes and renames code your app reaches only by reflection or JNI. How keep rules work, where they live in AGP 9.3+, and why narrow rules protect performance.
An app that works in debug builds and crashes after a release build is a classic R8 symptom. The release build is not "broken" - R8, the Android Gradle plugin's optimizer, renamed or removed code that your app reaches only indirectly, and the fix is usually a small, precise keep rule rather than a broad one.
This guide follows Android's official keep-rules documentation and the Android Developers Blog troubleshooting post, checked on 19 November 2026. It explains the concepts and shows current configuration formats; it is not a substitute for testing your own release build, and it does not cover every rule in the ProGuard syntax reference.
What R8 changes in a release build
When you enable app optimization with the default settings, R8 performs whole-program optimization: it removes code that appears unused, inlines methods, merges classes, and renames (obfuscates) classes, fields and methods. R8 can see and preserve every direct call in your code. The failures start where your code is reached in ways static analysis cannot follow.
Two dynamic patterns account for most keep-rule work:
- Reflection. R8 cannot identify a method looked up by name with
Class.getDeclaredMethod()or an annotation read withClass.getAnnotation(). It may rename or remove them, and the app then fails at runtime withClassNotFoundExceptionorNoSuchMethodException. - JNI. When native C or C++ code calls into Java or Kotlin (or the reverse) through the Java Native Interface, the call is a dynamic string lookup of the method name. R8 cannot see it either.
If your own code uses reflection, Android's documentation recommends annotating that code with Jetpack Keep annotations instead of hand-writing rules; the Gradle plugin generates the keep rules from the annotations at build time. The same documentation advises limiting reflection and choosing libraries that are compatible with R8 optimization in the first place.
Narrow rules protect the build; broad rules quietly cancel it
Every keep rule is an instruction to limit optimization. A well-crafted rule keeps exactly the entry point that dynamic execution needs and lets R8 optimize everything else. A broad rule does the opposite. Android's documentation lists the costs of overly broad rules directly: bloated DEX binaries, a larger app memory footprint, slower startup times, and higher ANR rates.
Three anti-patterns from the Android Developers Blog are worth recognizing in your own configuration:
- The package-wide keep.
-keep class com.example.** { *; }tells R8 not to shrink, obfuscate or optimize anything in that package or its sub-packages. It is the most common way teams "fix" a release crash and give up the benefits at the same time. - The negation trap.
-keep class !com.example.my_package.** { *; }does not mean "do not keep this package". It means "keep every class, method and property in the entire application outside this package". If a negation surprises you, check for others in your configuration. - Keeping standard components by hand. Activities, Services and BroadcastReceivers do not need manual rules - the default Android platform rules already cover them. Many libraries also ship their own keep rules; if a library's rules look wrong, raise it with the library author instead of layering your own on top.
Where keep rules live in current AGP
The configuration format depends on your Android Gradle plugin version.
For AGP 9.3 and higher, add rules to files with the .keep suffix in the src/<source set>/keepRules directory, for example src/main/keepRules/custom-rules.keep. The updated DSL enables code and resource optimization together:
android {
buildTypes {
release {
optimization {
enable = true // code and resource optimization
}
}
}
}
With this DSL, the default Android platform keep rules are included automatically. To manage every rule yourself, set optimization.keepRules.includeDefault to false - an advanced option most apps should leave alone.
On older AGP versions, the legacy DSL is still supported: custom rules go in a text file, conventionally proguard-rules.pro in the module root, referenced from the release build type with proguardFiles. If you use the legacy format, make sure the default file is proguard-android-optimize.txt - the outdated proguard-android.txt ships the platform keep rules without enabling R8's optimizations.
In multi-module apps, put keep rules in the library module next to the code they protect rather than collecting them in the app module. Library authors declare rules that travel with the library, so consumers get correct behavior without copying configuration.
Audit the rules you already have
Keep rules accumulate. A rule added during a frantic release week tends to stay forever, and third-party libraries bring rules you never reviewed. Android provides the R8 Configuration Analyzer to find broad or unnecessary keep rules, including those from dependencies. It reports shrinking, optimization and obfuscation scores that show how much of your code R8 is actually allowed to optimize. Run it before adding new rules and after cleaning old ones.
A working rule of thumb
Write the minimal contract your dynamic execution needs: the exact class, method or field that reflection or JNI touches. Test the release build, not the debug build, before shipping. If a release crash points at missing code, resist the package-wide keep and find the one entry point that needs preserving.
Keep rules are one part of a release pipeline. For the surrounding pieces, see our guides to Android upload and signing keys, what your team actually publishes (AAB vs APK), and the mobile app security checklist for founders. If you are planning an Android build or rescue, our Android app development page describes how engagements are scoped.
Sources
- Android Developers, About keep rules: https://developer.android.com/topic/performance/app-optimization/keep-rules-overview
- Android Developers Blog, Configure and troubleshoot R8 Keep Rules (18 November 2025): https://developer.android.com/blog/posts/configure-and-troubleshoot-r8-keep-rules
- Guardsquare ProGuard manual, usage and configuration reference: https://www.guardsquare.com/manual/configuration/usage
Drafted with AI assistance from these sources. Configuration formats change with AGP releases; check the official documentation and test your own release build before relying on any detail.