Android APK 16KB Page Size Compatibility Tool

A comprehensive shell script tool for analyzing and fixing Android APKs to ensure compatibility with 16KB page size devices.

Overview

Starting with Android 15, some devices use 16KB memory page sizes instead of the traditional 4KB. Additionally, Android R+ (API 30+) introduced stricter APK packaging requirements. APKs need specific alignment requirements to run efficiently on these devices:

• Native libraries (.so files) must be stored uncompressed in the APK
• Native libraries must be aligned to 16KB boundaries within the ZIP file
• resources.arsc must be stored uncompressed and aligned to 4-byte boundaries (Android R+)
• ELF segments within libraries must have proper internal alignment

This tool automates the detection and fixing of these compatibility issues.

Features

• 🔍 Comprehensive Analysis: Detects ZIP alignment issues and provides ELF alignment insights
• 🔧 Automatic Fixing: Rebuilds APKs with proper 16KB alignment while preserving all metadata
• � Android R+ Support: Handles resources.arsc uncompressed storage and 4-byte alignment requirements
• �📦 AAB Support: Full Android App Bundle support with conversion to APK for fixing
• 🔐 APK Signing: Optional automatic signing during fix process or standalone signing
• 📈 Version Management: Interactive version code/name setting for testing workflows
• 🚀 Auto-Detection: Automatically finds Android SDK, NDK, and build tools
• 📊 Detailed Reporting: Clear status reporting with color-coded output and smart compatibility logic

Overview

Starting with Android 15, some devices use 16KB memory page sizes instead of the traditional 4KB. APKs need specific alignment requirements to run efficiently on these devices:

• Native libraries (.so files) must be stored uncompressed in the APK
• Native libraries must be aligned to 16KB boundaries within the ZIP file
• ELF segments within libraries must have proper internal alignment

This tool automates the detection and fixing of these compatibility issues.

Features

• 🔍 Comprehensive Analysis: Detects both ZIP alignment and ELF alignment issues
• 🔧 Automatic Fixing: Rebuilds APKs with proper 16KB alignment while preserving all metadata
• ✅ Verification: Validates that fixed APKs meet 16KB compatibility requirements
• � APK Signing: Optional automatic signing during fix process or standalone signing
• 🔑 Keystore Management: Create new keystores for APK signing
• �🚀 Auto-Detection: Automatically finds Android SDK, NDK, and build tools
• 📊 Detailed Reporting: Clear status reporting with color-coded output

Requirements

• Android SDK (with build-tools 30.0.0+)
• Android NDK (for ELF analysis)
• apktool (for APK decompilation/recompilation)
• bundletool (for AAB support - optional but recommended)
• Python 3 (for precise alignment calculations)
• Java JDK (for APK signing - keytool and jarsigner)
• Standard Unix tools: unzip, aapt

Installation

1. Download the script:

   curl -O https://raw.githubusercontent.com/your-repo/16kb-apk-tool.sh
   chmod +x 16kb-apk-tool.sh

2. Ensure dependencies are installed:

   • Install Android SDK and set ANDROID_HOME or ANDROID_SDK_ROOT
   • Install apktool: brew install apktool (macOS) or equivalent
   • Install bundletool: brew install bundletool (macOS) or download from GitHub
   • Python 3 should be available as python3

Usage

The tool provides three core commands with flexible options for different workflows:

Analyze APK/AAB Compatibility

./16kb-apk-tool.sh audit your_app.apk
./16kb-apk-tool.sh audit your_app.aab

This command:

• Checks APK/AAB metadata (version codes, etc.)
• Analyzes ZIP alignment of all .so files
• Examines ELF internal alignment (informational)
• Uses smart logic: ZIP alignment determines compatibility, ELF alignment is advisory
• Provides a comprehensive compatibility report

Fix APK/AAB for 16KB Support

./16kb-apk-tool.sh fix your_app.apk
./16kb-apk-tool.sh fix your_app.aab

For APK files:

• Decompiles the APK using apktool
• Configures build settings to store .so files uncompressed
• Rebuilds the APK with proper structure
• Applies precise 16KB alignment to all native libraries
• Preserves all APK metadata (version codes, signatures, etc.)
• Outputs: your_app_16kb_fixed.apk

For AAB files:

• Converts AAB to universal APK using bundletool
• Applies the same APK fixing process above
• Outputs: your_app_from_aab_16kb_fixed.apk
• Note: Cannot convert back to AAB (technical limitation)

Fix and Sign APK in One Step

./16kb-apk-tool.sh fix your_app.apk --sign your_keystore.jks
./16kb-apk-tool.sh fix your_app.aab --sign your_keystore.jks

This command performs the same fix process above, then automatically signs the resulting APK with your keystore.

Fix with Interactive Version Setting

./16kb-apk-tool.sh fix your_app.apk --set-version

This command allows you to:

• Interactively enter version code and version name
• Replace existing version information or add if missing
• Review current version before setting new values
• Validate input to ensure proper version formats

Complete Workflow (Fix + Version + Sign)

./16kb-apk-tool.sh fix your_app.apk --set-version --sign your_keystore.jks

This combines all operations: fixes 16KB compatibility, sets version, and signs the APK.

Sign an Existing APK

./16kb-apk-tool.sh sign your_app.apk your_keystore.jks

This command:

• Signs the APK using apksigner (preferred) or jarsigner fallback
• Verifies the signature
• Maintains proper alignment during signing
• Outputs: your_app_signed.apk

Note: AAB signing is handled by Google Play during upload process.

Example Output

Audit (Problematic APK)

[INFO] Auditing APK: my_app.apk
===============================================
[INFO] APK Information:
package: name='com.example.app' versionCode='17' versionName='1.4.1'

[INFO] ZIP Alignment Analysis:
   4680721 lib/arm64-v8a/libapp.so (BAD - 11281)
   7882985 lib/arm64-v8a/libflutter.so (BAD - 2281)

[INFO] Analyzing ELF alignment...
[ERROR] lib/arm64-v8a/libapp.so: NOT ALIGNED (alignment < 16KB)
[ERROR] lib/arm64-v8a/libflutter.so: NOT ALIGNED (alignment < 16KB)

[ERROR] APK is NOT 16KB page compatible
[ERROR] Issues found:
[ERROR] - ZIP alignment: 2 .so files not aligned to 16KB boundaries
[INFO] Run '16kb-apk-tool.sh fix my_app.apk' to fix these issues

Audit (Fixed APK)

[INFO] Auditing APK: my_app_16kb_fixed.apk
===============================================
[INFO] APK Information:
package: name='com.example.app' versionCode='17' versionName='1.4.1'

[INFO] ZIP Alignment Analysis:
        44 resources.arsc (4B alignment: OK, uncompressed)
     16384 lib/arm64-v8a/libapp.so (16KB alignment: OK)
   8159232 lib/arm64-v8a/libflutter.so (16KB alignment: OK)

[INFO] Analyzing ELF alignment...
[ERROR] lib/arm64-v8a/libapp.so: NOT ALIGNED (alignment < 16KB)
[ERROR] lib/arm64-v8a/libflutter.so: NOT ALIGNED (alignment < 16KB)

[SUCCESS] APK is 16KB page compatible
[WARNING] Note: Some ELF libraries have internal alignment < 16KB
[WARNING] This doesn't affect 16KB page compatibility (ZIP alignment is what matters)
[INFO] Your APK will work correctly on 16KB page size devices

Audit (Signed APK with Minor Alignment Issues)

[INFO] Auditing APK: my_app_16kb_fixed_signed.apk
===============================================
[INFO] APK Information:
package: name='com.example.app' versionCode='17' versionName='1.4.1'

[INFO] ZIP Alignment Analysis:
        44 resources.arsc (4B alignment: OK, uncompressed)
     16392 lib/arm64-v8a/libapp.so (16KB alignment: BAD - 8)
   8159232 lib/arm64-v8a/libflutter.so (16KB alignment: OK)

[SUCCESS] APK is 16KB page compatible (with minor alignment variations)

[INFO] Minor alignment variations detected (typically from signing):
[INFO] - lib/arm64-v8a/libapp.so (offset: 8 bytes)
[INFO] These small offsets rarely cause compatibility issues in practice.
[INFO] Your APK will work correctly on 16KB page size devices

Fix (Interactive Version Setting)

[INFO] Fixing APK for 16KB compatibility: my_app.apk
[INFO] Will set version interactively during fixing
[INFO] Step 1: Decompiling APK...
[INFO] Current AndroidManifest.xml version information:
[INFO]   Current Version Code: 17
[INFO]   Current Version Name: 1.4.1

Enter new version code [18]: 20
Enter new version name [1.4.1]: 1.5.0
[INFO] Created backup: AndroidManifest.xml.backup
[SUCCESS] Updated version code: 17 → 20
[SUCCESS] Updated version name: 1.4.1 → 1.5.0

[INFO] Version update completed!
[INFO] Step 2: Configuring for uncompressed .so files and resources.arsc...
[INFO] Step 3: Rebuilding APK...
[INFO] Step 4: Applying precise 16KB alignment...
[INFO] Step 5: Verifying the result...
[SUCCESS]       44 resources.arsc (4B alignment: OK, uncompressed)
[SUCCESS]   458752 lib/arm64-v8a/libapp.so (16KB alignment: OK)
[SUCCESS]  8601600 lib/arm64-v8a/libflutter.so (16KB alignment: OK)

[SUCCESS] Successfully created 16KB-aligned APK: my_app_16kb_fixed.apk
[SUCCESS] All 6 .so files are properly aligned
[SUCCESS] resources.arsc is properly aligned and uncompressed

Fix and Sign (Complete Workflow)

[INFO] Fixing APK for 16KB compatibility: my_app.apk
[INFO] Will sign APK after fixing with: my_key.jks
[INFO] Step 1: Decompiling APK...
[INFO] Step 2: Configuring for uncompressed .so files and resources.arsc...
[INFO] Step 3: Rebuilding APK...
[INFO] Step 4: Applying precise 16KB alignment...
[INFO] Step 5: Verifying the result...
[SUCCESS]       44 resources.arsc (4B alignment: OK, uncompressed)
[SUCCESS]   458752 lib/arm64-v8a/libapp.so (16KB alignment: OK)
[SUCCESS]  8601600 lib/arm64-v8a/libflutter.so (16KB alignment: OK)

[SUCCESS] Successfully created 16KB-aligned APK: my_app_16kb_fixed.apk
[SUCCESS] All 6 .so files are properly aligned
[SUCCESS] resources.arsc is properly aligned and uncompressed
[INFO] Proceeding with APK signing...
Enter keystore password: ********
[INFO] Using alias: my_key
[INFO] Signing APK with apksigner (preserving alignment)...
[SUCCESS] APK signed successfully: my_app_16kb_fixed_signed.apk
[SUCCESS] Signature verification passed

AAB Processing

[INFO] AAB detected - converting to APK for 16KB fixing...
[INFO] Step 1: Converting AAB to universal APK...
[SUCCESS] AAB converted to APK: my_app_from_aab.apk
[INFO] Proceeding with APK fixing on converted file...

=== AAB Processing Complete ===
[INFO] Your AAB has been converted to a 16KB-compatible APK.

[WARNING] Note: Converting back to AAB is not supported because:
[WARNING] - AABs are build-time artifacts with modular structure
[WARNING] - APKs are compiled runtime artifacts
[WARNING] - Google Play signs AABs during upload

[INFO] For production AABs, modify your build process instead:
[INFO] 1. Add to your app's build.gradle:
[INFO]    android {
[INFO]      packagingOptions {
[INFO]        jniLibs {
[INFO]          useLegacyPackaging = false
[INFO]        }
[INFO]      }
[INFO]    }
[INFO] 2. Ensure your native libraries are built with 16KB alignment
[INFO] 3. Upload the rebuilt AAB to Google Play

Technical Details

What the Tool Does

1. Analysis Phase:

   • Extracts ZIP file structure and calculates .so file positions
   • Uses NDK objdump to analyze ELF segment alignment (informational)
   • Checks against 16KB (16384 byte) alignment requirements
   • Smart Logic: ZIP alignment determines compatibility; ELF alignment is advisory

2. Fix Phase:

   • Handles both APK and AAB inputs (converts AAB to APK for processing)
   • Decompiles APK using apktool to preserve metadata
   • Optionally sets version code and name interactively in AndroidManifest.xml
   • Modifies apktool.yml to force uncompressed storage for .so files and resources.arsc
   • Rebuilds APK with proper Android resource compilation
   • Applies precise ZIP alignment: 16KB boundaries for .so files, 4-byte for resources.arsc
   • Ensures compatibility with both 16KB page devices and Android R+ requirements

3. Signing Phase:

   • Uses apksigner (preferred) for modern APK v1/v2 signing
   • Falls back to jarsigner for compatibility
   • Maintains alignment during signing process
   • Validates signature integrity

Size Impact

Fixed APKs will be larger because native libraries are stored uncompressed:

• Typical increase: ~2x size due to uncompressed .so files
• Trade-off: Larger download vs. better runtime performance on 16KB devices
• AAB recommendation: For production, rebuild from source with proper settings and upload as AAB
• APK distribution: Direct APK distribution will have larger file sizes

Version Management

The tool provides interactive version management during the fix process:

Interactive Setting:

• Manual Input: Enter exact version code and name via terminal prompts
• Current Display: Shows existing version information before prompting
• Smart Defaults: Suggests incremented values based on current versions
• Add or Replace: Automatically handles missing version attributes
• Validation: Ensures version code is numeric
• Backup: Creates .backup file before modification

This is particularly useful for:

• Development builds where you need specific version numbers
• Testing workflows where version tracking is important
• QA processes that require unique APK versions
• Missing versions where attributes need to be added to manifest

Compatibility

• Android versions: Fixes apply to all Android versions
• Devices: Ensures compatibility with both 4KB and 16KB page devices
• Performance: Improves app startup on 16KB devices
• Backwards compatibility: No impact on existing 4KB page devices

Troubleshooting

"Android SDK not found"

Set the environment variable:

export ANDROID_HOME=/path/to/your/android/sdk
# or
export ANDROID_SDK_ROOT=/path/to/your/android/sdk

"bundletool not found"

Install bundletool for full AAB support:

# macOS
brew install bundletool

# Or download from GitHub
wget https://github.com/google/bundletool/releases/latest/download/bundletool-all.jar
chmod +x bundletool-all.jar
# Add to PATH or create wrapper script

"No compatible build-tools version found"

Install a recent build-tools version:

sdkmanager "build-tools;35.0.1"

"apktool not found"

Install apktool:

# macOS
brew install apktool

# Linux
apt-get install apktool

# Or download directly from https://apktool.org/

"keytool not found" or "jarsigner not found"

Install Java JDK:

# macOS
brew install openjdk

# Linux
apt-get install openjdk-11-jdk

# Or download from Oracle/OpenJDK

APK Signing Issues

• Wrong password: Ensure keystore and key passwords are correct
• Invalid alias: Use keytool -list -keystore your_keystore.jks to see available aliases
• Keystore format: Tool supports JKS keystores
• Signature method: Uses apksigner (preferred) or jarsigner fallback

"ELF libraries have insufficient alignment"

This is usually informational only. The tool uses smart logic:

• ZIP alignment = Critical for 16KB compatibility ✅
• ELF alignment = Internal library structure (not critical for 16KB pages) ⚠️

If you see ELF alignment warnings but ZIP alignment is OK, your APK will work on 16KB devices.

For eliminating ELF warnings completely:

1. Rebuild the app from source with NDK 21+ and android:extractNativeLibs="false"
2. Use proper linker flags during native library compilation

Limitations

• AAB conversion: AAB → APK is supported, but APK → AAB conversion is not possible
• File size: Uncompressed libraries increase APK size significantly
• Source builds: Best results come from rebuilding from source with proper settings
• ELF warnings: Internal ELF alignment warnings don't affect 16KB compatibility
• Signing scope: Only APK signing supported (AABs are signed by Google Play)

Related Information

• Android 16KB page size guidance
• APK optimization guide
• Native library packaging

License

This tool is provided as-is for educational and development purposes. Please ensure compliance with your organization's policies and the Android ecosystem requirements.