verify-16k-page-align


A shell script and npm package to verify if your Android APK/AAB/APEX native libraries are aligned to 16KB or 64KB memory pages. This is required for compatibility with Android 15+ devices and Google Play submissions after November 1, 2025 (see official docs).

---

Table of Contents

- Features
- Why 16KB Page Alignment?
- Installation
- Usage
- CI/CD Integration
- How It Works
- Platform Support
- Requirements
- Migration Guide
- Troubleshooting
- FAQ
- Contributing
- References
- Support
- License

---

Features

- Checks all native .so libraries in APK, AAB, and APEX files for 16KB or 64KB page alignment.
- Supports scanning extracted directories containing native libraries.
- Uses objdump to analyze ELF program headers.
- CI/CD Ready: Returns exit code 1 on failure, 0 on success.
- Includes APK zip-alignment verification (requires Android build-tools 35.0.0-rc3+).
- Fast, zero dependencies (besides unzip/objdump).
- CLI and npm global install.
- Supports both arm64-v8a and x86_64 architectures.

---

Why 16KB Page Alignment?

Starting with Android 15, many devices will use 16KB memory pages for improved performance and reliability. All apps targeting Android 15+ and distributed via Google Play must ensure their native libraries (.so files) are 16KB or 64KB aligned. See:
- Android Developers: 16 KB Page Size
- Google Play Blog: Prepare for 16 KB page size
- Medium: Android 15 Mandatory 16KB Memory Page Size

Benefits:
- Faster app launches (3–30% improvement)
- Lower battery usage
- Reduced memory fragmentation
- Required for Play Store submission (from Nov 2025)

---

Installation

$3

``sh
sh -c "$(curl -fsSL https://raw.githubusercontent.com/hotbrainstech/verify-16k-page-align/main/src/verify-16k-page-align.sh)"
`

$3

`sh
sudo npm i -g verify-16k-page-align
`

---

Usage

$3

By default, only arm64-v8a libraries are checked. To also check x86_64 libraries, add x86 as a second argument.

#### Using NPM package
`sh


Default: check arm64-v8a only

verify-16k-page-align path/to/app.apk
verify-16k-page-align path/to/app.aab

Check arm64-v8a and x86_64

verify-16k-page-align path/to/app.apk x86
`

#### Using local script
Make sure the script is executable:
`sh
chmod +x ./src/verify-16k-page-align.sh

Run


./src/verify-16k-page-align.sh path/to/app.apk
`

$3

You can also run the script against a directory containing extracted native libraries (must follow lib/arm64-v8a/ structure).

`sh
verify-16k-page-align path/to/extracted/libs
`

$3

`
=== APK zip-alignment ===
lib/arm64-v8a/libfoo.so: 16384 (OK - 16KB aligned)
lib/arm64-v8a/libbar.so: 4096 (BAD - 4KB aligned)
Verification FAILED
=========================

=== ELF alignment ===
lib/arm64-v8a/libfoo.so: ALIGNED (2**14)
lib/arm64-v8a/libbar.so: UNALIGNED (2**12)
Found 1 unaligned libs (only arm64-v8a/x86_64 libs need to be aligned).
=====================
`

---

CI/CD Integration

This tool is designed for CI/CD pipelines. It returns a non-zero exit code if verification fails.

$3

`yaml
name: Verify 16KB Alignment

on: [push, pull_request]

jobs:
verify-alignment:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3

# Install dependencies (objdump is usually present, but just in case)
- name: Install dependencies
run: sudo apt-get update && sudo apt-get install -y binutils unzip

- name: Install verify-16k-page-align
run: sudo npm i -g verify-16k-page-align

- name: Verify APK
run: verify-16k-page-align path/to/your-app-release.apk
`

---

How It Works

1. Extraction:
- For APK/AAB: Unzips lib/ directory to a temporary location.
- For APEX: Uses deapexer to extract contents.
2. APK Zip Alignment: If checking an APK and zipalign is available (build-tools 35.0.0-rc3+), verifies 16KB zip alignment.
3. ELF Analysis: Scans all .so files using objdump to inspect ELF program headers.
4. Validation: Checks if LOAD segments are aligned to 16KB (214) or 64KB (216).
5. Result:
- Prints status for each library.
- Exits with 1 if any unaligned libraries are found.

---

Platform Support

- Linux (Ubuntu, Debian, Fedora, etc.)
- macOS (requires GNU binutils)
- Windows (Not supported directly; use WSL2)

---

Requirements

- unzip (for extracting APK/AAB contents)
- objdump (from binutils, for ELF analysis)
- zipalign (Optional: from Android build-tools 35.0.0-rc3+, for zip alignment check)
- deapexer (Optional: for APEX file support)

$3


macOS objdump may not support all flags. Install GNU binutils:

`sh
brew install binutils


Ensure gobjdump is in your PATH or linked as objdump


`

---

Migration Guide

If your app or any dependency uses native code:
1. Update your build tools: Use Android Gradle Plugin (AGP) >= 8.5.1 and NDK r27+ (prefer r28+).
2. Recompile all native libraries with 16KB alignment.
3. Remove hardcoded page size assumptions (replace 4096/0x1000/PAGE_SIZE with sysconf(_SC_PAGESIZE)).
4. Check all third-party .so files for compliance.
5. Test on Android 15+ emulators or real devices.

See official migration steps.

---

Troubleshooting

- UNALIGNED (212)**: The library is 4KB aligned. You must rebuild it with NDK r27+ or add linker flags.
- command not found: verify-16k-page-align: Ensure npm global bin is in your PATH, or use the shell script directly.
- objdump: command not found: Install binutils.
- Permission denied: Run chmod +x verify-16k-page-align.sh before executing.

---

FAQ

Q: Does this work for Java/Kotlin-only apps?
A: No need—Java/Kotlin-only apps do not use native libraries and are already compatible.

Q: What if my library is not 16KB aligned?
A: Update your build tools and recompile. Contact third-party vendors for updated .so files.

Q: Can I use this on macOS?
A: Yes, install binutils` via Homebrew.

Q: Is this required for Play Store submission?
A: Yes, for Android 15+ apps after Nov 1, 2025.

---

🤝 Contributing

Pull requests and issues are welcome! See GitHub Issues.

---

References & Further Reading

- Android 16KB Page Size Docs
- Google Play Blog
- Medium: Migration Guide

Show your support

Give a ⭐️ if this project helps you!

Or buy me a coffee 🙌🏾

📝 License

Copyright © 2025 @hotbrainstech.

This project is MIT licensed.