Android 16 KB page size alignment
Quick Reference
| Item | Details |
|---|---|
| Google Play requirement | Apps and updates targeting Android 15+ must support 16 KB page sizes on 64-bit devices |
| React Native support | RN 0.79+ includes aligned RN-provided native binaries; still verify third-party .so files |
| What to check | Third-party native libraries (.so files) |
| Official documentation | developer.android.com/guide/practices/page-sizes |
Quick Command
Verify generated APK alignment using Android's official zipalign tool:
zipalign -c -P 16 -v 4 app-release.apkIf any 64-bit libraries (arm64-v8a, x86_64) show misalignment, they need updating.
For deeper ELF-level inspection, use Android's check_elf_alignment.sh script.
When to Check
React Native 0.79+ builds core binaries with correct alignment. However, third-party native libraries may still be misaligned. Check alignment when:
- Adding or updating SDKs with native code
- Preparing a release for Google Play
- Investigating crashes on Android 15+ devices with 16 KB page size
CI Integration
Add alignment checks to your release pipeline after producing release APKs. If you ship AABs, generate device APKs with your normal release tooling or bundletool, then run zipalign on those APKs:
zipalign -c -P 16 -v 4 app-release.apk 2>&1 | tee alignment.log
if grep -q "Verification FAILED" alignment.log; then exit 1; fiStep-by-Step
- Build your release artifact
- Generate or locate the release APK(s)
- Run
zipalignverification (see Quick Command) - If misaligned libraries are found, trace them to source packages (see below)
- Update, replace, or remove the affected dependencies
For runtime testing, use the 16KB Android Emulator image or enable "Boot with 16KB page size" on Pixel 8/8a/9 devices.
Tracing Misaligned Libraries
When zipalign reports a misaligned library like libfoo.so, find its source package:
# Find the .so file in node_modules
find node_modules -name "libfoo.so" 2>/dev/null
# Or search gradle files for references
grep -r "foo" node_modules/*/android --include="*.gradle" 2>/dev/nullOnce identified, update the dependency or contact the vendor for a 16KB-compatible build.
Common Pitfalls
- Waiting for Play Store rejection instead of checking in CI
- Assuming a React Native upgrade rebuilds third-party native binaries
- Only checking 32-bit ABIs (
armeabi-v7a,x86) — these are not affected - Using
zipalignwithout the-P 16flag (checks 4 KB, not 16 KB) - Validating only debug builds
Fixing Alignment Issues
Alignment issues require rebuilding the native library with a compatible toolchain. Repackaging alone does not fix them.
See official remediation steps for detailed guidance.
Related Skills
- native-profiling.md — Native debugging tools