Amol Pawar

Most Android performance improvements land as a framework update or a new API. This one is different. Starting with Android 15, Google added support for a 16 KB page size on ARM64 devices — and with Android 16, it’s becoming a hard requirement for apps that target new hardware.

If you haven’t looked into this yet, now is a good time. Apps that ship 4 KB-aligned native libraries will fail to load on 16 KB page-size devices. The failure isn’t graceful — it’s an UnsatisfiedLinkError and a crash.

This guide covers what the change is, which apps are affected, how to check your own APK, and what to actually do about it.

Memory Pages: A Quick Refresher

The OS doesn’t allocate memory one byte at a time — it works in fixed-size blocks called pages. For decades, Android (like most Linux systems) used a 4 KB page size. That made sense when RAM was limited and apps were simpler.

Modern flagship devices are a different story. They have multiple gigabytes of RAM, 64-bit ARM processors, and apps that load dozens of native libraries at startup. Managing all of that in 4 KB chunks means more page table entries, more TLB pressure, and more overhead on every app launch.

16 KB pages reduce that overhead. The OS manages fewer, larger chunks — fewer page faults at startup, fewer TLB misses during execution, and less kernel bookkeeping overall.

Why Google Made the Change

The performance case is real:

Faster cold starts. Fewer pages need to be mapped during app startup. Google’s benchmarks showed cold launch improvements of up to 30% on devices running a 16 KB page-size kernel.

Better TLB efficiency. The TLB (Translation Lookaside Buffer) is a small hardware cache that maps virtual addresses to physical memory. With 16 KB pages, each TLB entry covers four times more memory, which means fewer misses on cache-heavy operations.

Less kernel overhead. Fewer pages means a smaller page table. The kernel spends less time on memory management and more time running your code.

Industry alignment. Apple has used 16 KB pages on ARM devices for years. The mainline Linux kernel has progressively added support too. Android isn’t ahead of the curve here — it’s catching up.

Where Things Stand in 2026

• Android 15 introduced 16 KB page size support in the emulator so developers could start testing.
• Android 16 is expected to require 16 KB compliance for apps targeting API 36 on supported hardware.
• Pixel 9 and later are expected to ship with kernels configured for 16 KB pages.
• Play Console already shows warnings for apps that bundle 4 KB-aligned .so files when targeting API 35+.

The install base of 16 KB devices is still small, but it will grow quickly as new flagships ship. Getting ahead of this now is much easier than scrambling when Play starts rejecting updates.

Does This Affect Your App?

It depends entirely on whether your app includes native code.

Pure Kotlin or Java apps

You’re largely fine. The Android Runtime handles .dex alignment automatically, so managed code isn’t affected. The one thing to watch is third-party SDKs — they sometimes bundle native .so files you didn’t write and may not have checked.

Apps with NDK or native libraries

This is where the requirement has real teeth. If your app includes:

• Native libraries (.so files) built with the NDK
• Pre-built .so files from third-party SDKs
• A game engine like Unity or Cocos2d
• Audio, video, or image processing libraries with native bindings

…then every one of those .so files needs to be compiled with 16 KB-aligned ELF segments. If any aren’t, the OS on a 16 KB device will refuse to load them.

Check Your APK

Before touching any build config, find out where you actually stand.

Use readelf on your .so files

# Unzip the APK
unzip your-app.apk -d app-contents

# Inspect a native library
readelf -l app-contents/lib/arm64-v8a/libyourlibrary.so | grep LOAD

Look at the alignment column on the right side of each LOAD segment line:

• 0x4000 = 16384 bytes = 16 KB compliant
• 0x1000 = 4096 bytes = 4 KB needs recompiling

Compliant output:

LOAD  0x000000 ... 0x001abc 0x001abc R   0x4000
LOAD  0x002000 ... 0x005def 0x005def R E 0x4000

Non-compliant output:

LOAD  0x000000 ... 0x001abc 0x001abc R   0x1000

Do this for every .so in the APK, not just the ones you wrote. Third-party libraries need to pass too.

Run AGP’s built-in lint check

Android Gradle Plugin 8.5+ includes a lint check specifically for this. Run:

./gradlew lint

Look for warnings tagged PageSizeAlignment. They’ll call out each non-compliant library by name.

Fix Your Own Native Libraries

If you maintain native code with the NDK, the fix is a single linker flag.

With CMake

# CMakeLists.txt

cmake_minimum_required(VERSION 3.22.1)
project(MyNativeLib)

add_library(
    mynativelib
    SHARED
    src/main/cpp/mynativelib.cpp
)

# Tell the linker to align ELF LOAD segments to 16 KB boundaries
target_link_options(mynativelib PRIVATE "-Wl,-z,max-page-size=16384")

find_library(log-lib log)

target_link_libraries(
    mynativelib
    ${log-lib}
)

The flag -Wl,-z,max-page-size=16384 passes max-page-size=16384 directly to the linker. It sets the alignment of every LOAD segment in the output .so to 16 KB. That’s all the change requires on your end.

With ndk-build

# Android.mk

LOCAL_PATH := $(call my-dir)

include $(CLEAR_VARS)

LOCAL_MODULE    := mynativelib
LOCAL_SRC_FILES := mynativelib.cpp

# 16 KB page size alignment
LOCAL_LDFLAGS   := -Wl,-z,max-page-size=16384

include $(BUILD_SHARED_LIBRARY)

After rebuilding, re-run the readelf check to confirm the alignment value changed from 0x1000 to 0x4000.

One thing worth knowing: a 16 KB-aligned .so runs fine on 4 KB devices too. The extra alignment padding is harmless on older hardware. You don’t need separate builds — one .so covers both.

Kotlin: What You Need to Handle

Kotlin doesn’t control ELF alignment, but there are places where Kotlin code loads native libraries and should handle failures gracefully.

Safe native library loading

System.loadLibrary() throws UnsatisfiedLinkError if a .so fails to load — which on a 16 KB device usually means the library isn’t aligned. Without handling this, the app just crashes.

// NativeLibraryLoader.kt

object NativeLibraryLoader {

    private const val TAG = "NativeLibraryLoader"

    /**
     * Loads a native library and returns false (instead of crashing)
     * if it fails. On 16 KB page-size devices, an UnsatisfiedLinkError
     * usually means the .so wasn't compiled with max-page-size=16384.
     */
    fun loadSafely(libraryName: String): Boolean {
        return try {
            System.loadLibrary(libraryName)
            Log.d(TAG, "Loaded: lib$libraryName.so")
            true
        } catch (e: UnsatisfiedLinkError) {
            Log.e(
                TAG,
                "Failed to load lib$libraryName.so — possible 16 KB alignment issue. " +
                "Recompile with: -Wl,-z,max-page-size=16384",
                e
            )
            false
        } catch (e: SecurityException) {
            Log.e(TAG, "Security exception loading lib$libraryName.so", e)
            false
        }
    }
}

Use it in your Activity or Application:

// MainActivity.kt

class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        val loaded = NativeLibraryLoader.loadSafely("mynativelib")

        if (!loaded) {
            showCompatibilityError()
        }
    }

    private fun showCompatibilityError() {
        AlertDialog.Builder(this)
            .setTitle("Compatibility Issue")
            .setMessage(
                "A required component couldn't load on this device. " +
                "Try updating the app to get the latest compatibility fixes."
            )
            .setPositiveButton("OK", null)
            .show()
    }
}

This avoids a crash and gives the user a message they can actually act on, instead of a silent ANR.

Detecting page size at runtime

Sometimes you need to know which page size the device is using — for example, to decide whether to enable a feature backed by a library you haven’t fully audited yet.

// PageSizeDetector.kt

import android.system.Os
import android.system.OsConstants

/**
 * Reads the system page size at runtime using the POSIX sysconf API.
 * Returns 4096 on standard devices, 16384 on 16 KB page-size devices.
 */
object PageSizeDetector {

    fun getPageSizeInBytes(): Long {
        return Os.sysconf(OsConstants._SC_PAGESIZE)
    }

    fun is16KBPageSize(): Boolean {
        return getPageSizeInBytes() == 16384L
    }

    fun description(): String {
        return when (getPageSizeInBytes()) {
            4096L  -> "4 KB"
            16384L -> "16 KB"
            else   -> "${getPageSizeInBytes()} bytes (unknown)"
        }
    }
}

Log it at startup — it takes one line and has saved debugging time more than once when a crash report comes in from an unfamiliar device:

// App.kt

class App : Application() {
    override fun onCreate() {
        super.onCreate()
        Log.i("App", "Page size: ${PageSizeDetector.description()}")
    }
}

When you see a crash log from a device you can’t reproduce locally, the page size entry tells you whether you’re looking at an alignment problem or something else entirely.

Auditing bundled native libraries at debug time

This helper scans your app’s native library directory and lists every .so it finds. It won’t tell you the alignment directly (use readelf for that), but it gives you a complete list to work through — which matters when you’re auditing a project with a lot of dependencies.

// SdkCompatibilityChecker.kt

import java.io.File

/**
 * Lists all native libraries bundled in the APK at runtime.
 * Run this in debug builds to build your audit list.
 * For actual alignment verification, use readelf on each file.
 */
object SdkCompatibilityChecker {

    private const val TAG = "SdkCompatibilityChecker"

    fun findNativeLibraries(context: android.content.Context): List<String> {
        val nativeLibDir = File(context.applicationInfo.nativeLibraryDir)

        if (!nativeLibDir.exists() || !nativeLibDir.isDirectory) {
            Log.w(TAG, "No native library directory found.")
            return emptyList()
        }

        return nativeLibDir
            .listFiles { file -> file.name.endsWith(".so") }
            ?.map { it.name }
            ?: emptyList()
    }

    fun auditAndLog(context: android.content.Context) {
        val libs = findNativeLibraries(context)

        if (libs.isEmpty()) {
            Log.i(TAG, "No native libraries found.")
            return
        }

        Log.w(TAG, "Found ${libs.size} native libraries — verify each with readelf:")
        libs.forEach { Log.w(TAG, "  -> $it") }
    }
}

Wire it into your Application class behind a BuildConfig.DEBUG check:

class App : Application() {

override fun onCreate() {
        super.onCreate()
        if (BuildConfig.DEBUG) {
            SdkCompatibilityChecker.auditAndLog(this)
        }
    }
}

Every debug run now logs a full list of native libraries. Paste it into a spreadsheet, mark which ones you own, and track the audit from there.

Test on a 16 KB Emulator

You don’t need a physical device for this. Android Studio ships with 16 KB emulator images.

Create the emulator

1. Open Android Studio → Device Manager
2. Click Create Device
3. Pick a Pixel 8 or later hardware profile
4. On the system image screen, select an image labelled “16k page size” (available for API 35 and API 36)
5. Finish the setup and start the emulator

Confirm it’s configured correctly

adb shell getconf PAGE_SIZE

16384 means you’re on a 16 KB device. 4096 means something went wrong with the AVD setup.

What to watch for when running your app

• Crash on launch → a native library failed to load; check Logcat for the library name
• UnsatisfiedLinkError in Logcat → that specific .so is 4 KB aligned
• App runs normally → you’re compliant

Dealing With Third-Party Libraries You Can’t Recompile

Your code might be clean, but one of your dependencies is shipping a 4 KB-aligned .so that you have no control over.

Option 1 — Contact the vendor. File a GitHub issue or support ticket referencing the Android 16 KB page size requirement. Most major SDKs (Firebase, Google Play Services, Crashlytics) are already compliant. Smaller or older SDKs may need a nudge.

Option 2 — Gate the feature at runtime. While you wait for the vendor to ship a fix, use PageSizeDetector to disable the feature on affected devices:

// FeatureManager.kt

object FeatureManager {

    /**
     * Returns false on 16 KB page-size devices if the underlying
     * native library hasn't been verified as compliant yet.
     * Flip this to true once your SDK vendor ships a fix.
     */
    fun isNativeFeatureEnabled(): Boolean {
        if (PageSizeDetector.is16KBPageSize()) {
            Log.w("FeatureManager", "Skipping native feature on 16 KB device — awaiting SDK update.")
            return false
        }
        return true
    }
}

Option 3 — Write a Kotlin fallback. For features where a fallback is feasible, have two paths: the native implementation for standard devices, and a pure Kotlin path for 16 KB devices until the library is updated.

// ImageProcessor.kt

class ImageProcessor {

    /**
     * Uses the fast native path on verified devices, falls back to
     * Kotlin on 16 KB page-size devices until the native library is updated.
     */
    fun processImage(bitmap: android.graphics.Bitmap): android.graphics.Bitmap {
        return if (FeatureManager.isNativeFeatureEnabled()) {
            processImageNative(bitmap)  // C++ via JNI
        } else {
            processImageKotlin(bitmap)  // Pure Kotlin fallback
        }
    }

    private external fun processImageNative(
        bitmap: android.graphics.Bitmap
    ): android.graphics.Bitmap

    private fun processImageKotlin(
        bitmap: android.graphics.Bitmap
    ): android.graphics.Bitmap {
        val copy = bitmap.copy(bitmap.config, true)
        // apply transformations
        return copy
    }
}

This keeps the app working on all devices. The Kotlin path is slower, but it beats a crash.

Google Play Requirements

Play Console already flags 4 KB-aligned libraries as warnings when you target API 34 or lower. However, for API 35 (Android 15) and above, 16 KB compliance is now mandatory for all new apps and updates. While Google initially allowed extensions, as of 2026, non-compliant apps with native code will face immediate rejection during the upload process.

Check Play Console → Release → App bundle explorer → [Select Version] → Supported page sizes for any warnings or “Not Supported” labels regarding native library alignment. Deal with them immediately to ensure your releases are not blocked.

Real Performance Numbers

The gains are genuine but not uniform across all app types:

The trade-off: small allocations get rounded up to the next 16 KB boundary, so there’s a slight increase in memory usage. For most apps it’s a few hundred KB at most — well worth the startup speed improvement.

Migration Checklist

Android 16 KB Page Size - Pre-ship Checklist
=============================================

□ Unzipped APK and located all .so files under lib/arm64-v8a/
□ Ran readelf -l on each .so - confirmed LOAD alignment is 0x4000
□ Added -Wl,-z,max-page-size=16384 to CMakeLists.txt or Android.mk
□ Rebuilt native libraries - re-verified alignment with readelf
□ Audited all third-party .so files - opened tickets with non-compliant vendors
□ Added NativeLibraryLoader with UnsatisfiedLinkError handling
□ Added PageSizeDetector and logging to Application.onCreate()
□ Added SdkCompatibilityChecker to debug builds
□ Created a 16k page size AVD in Android Studio
□ Ran the app on the 16k emulator - no crashes, no UnsatisfiedLinkError
□ Ran ./gradlew lint - no PageSizeAlignment warnings
□ Checked Play Console - no native library alignment warnings

FAQ

Does this affect all Android devices right now?

No. The 16 KB page size requires specific kernel and hardware support. Older devices will keep using 4 KB pages. But as Pixel 9 and later devices ship with 16 KB kernels, the affected install base will grow steadily.

My app is pure Kotlin with no NDK. Do I need to do anything?

Probably not. ART handles alignment for managed code automatically. Just double-check your Gradle dependencies for any SDKs that bundle .so files — those are the only risk for a pure Kotlin app.

Will a 4 KB-aligned .so actually crash the app?

Yes. On a 16 KB page-size device, System.loadLibrary() will throw UnsatisfiedLinkError if the .so isn’t properly aligned. That’s an app crash unless you catch it.

Can one .so file work on both 4 KB and 16 KB devices?

Yes. A library compiled with -Wl,-z,max-page-size=16384 works fine on 4 KB devices — the extra alignment is just padding that gets ignored. You don’t need separate builds for different page sizes.

What about Unity?

Unity generates native .so files, so yes, it’s affected. Unity has been shipping fixes in recent LTS versions. Make sure you’re on an up-to-date Unity LTS release and rebuild your project after upgrading.

Conclusion

The Android 16 KB page size change is the kind of requirement that’s easy to ignore until it starts causing crashes on new hardware. The fix is straightforward if you own your native code — it’s one linker flag and a rebuild. The harder work is tracking down third-party SDKs that haven’t updated yet and building a plan for those.

Start by running the readelf check on your APK today. If everything comes back as 0x4000, you’re done. If not, the checklist above has every step you need.

If you’ve worked with Android long enough, you already know this: emulator performance isn’t just about speed, it’s about consistency.

A fast emulator that behaves unpredictably is worse than a slightly slower one that’s stable.

This guide focuses on Android Emulator Settings that hold up in real-world development. Not just for solo projects, but for teams, CI pipelines, and production-grade workflows.

How to Think About Emulator Performance

Before changing settings, it helps to understand what actually impacts emulator performance.

There are three main bottlenecks:

1. CPU virtualization overhead
2. Memory pressure (host + emulator)
3. GPU rendering pipeline

Most “tuning tips” online ignore this and suggest arbitrary numbers. In practice, performance tuning should be constraint-driven, not guesswork.

Core Android Emulator Settings That Make a Difference

Let’s go through the settings that consistently make a difference.

CPU Allocation: Less Is Often More

A common mistake is over-allocating CPU cores.

What works in practice:

• 2 cores → stable baseline (recommended for most cases)
• 3–4 cores → only if profiling shows CPU bottlenecks

Why this matters:
The emulator runs inside a virtualized environment. Giving it too many cores can increase context switching and hurt overall system responsiveness.

Rule of thumb:
If your host machine slows down, your emulator will too.

RAM Allocation: Avoid Starving the Host

This is where people usually overdo it.

• Start with 2–4 GB
• Increase only if you see real issues (UI lag, memory errors)

Giving the emulator too much RAM can slow down everything else on your system, which ends up hurting performance overall.

VM Heap Size

This one gets confused with RAM, but it’s not the same thing.

VM Heap controls how much memory an app inside the emulator can use, not the emulator itself.

• Default value is usually fine
• Increase only if you’re testing memory-heavy apps (large bitmaps, video, complex Compose UIs)

If you set it too high without a reason:

• You won’t see real benefits
• You may hide memory issues that show up on real devices

Practical note:
 If your app only runs after increasing VM Heap, that’s a signal to fix memory usage, not raise limits.

Watch for:

• OutOfMemoryError
• Frequent GC activity in Logcat
• UI stutter caused by memory pressure

System Images: x86_64 vs ARM (Context Matters in 2026)

For most desktop environments:

• x86_64 images → still the default for performance

However:

• On Apple Silicon (ARM hosts), ARM images can perform better due to reduced translation overhead.

Takeaway:
Choose the image based on your host architecture, not habit.

Hardware Acceleration: Non-Negotiable

Without hardware acceleration, nothing else will save you.

• Windows → WHPX / Hyper-V
• Linux → KVM
• macOS → Hypervisor.framework

If virtualization isn’t enabled in BIOS/UEFI, performance will collapse.

GPU Rendering: Prefer Hardware, Validate When Needed

Set graphics to:

• Hardware (GLES 2.0 or 3.0)

This improves:

• UI responsiveness
• Frame rendering
• Animation smoothness

When to switch to software:

• Debugging rendering issues
• Investigating device-specific GPU bugs

Resolution and Device Profile

Higher resolution increases GPU load.

Practical setup:

• Use 720p or 1080p for daily development
• Use higher resolutions only for layout validation

Avoid treating the emulator like a flagship device unless required.

Quick Boot vs Cold Boot: Know the Trade-Off

Quick Boot is convenient, but not always safe.

Use Quick Boot when:

• Iterating during development
• You need faster startup

Use Cold Boot when:

• Running tests
• Debugging inconsistent behavior
• Working in CI environments

Snapshots can introduce subtle state issues that are hard to trace.

Settings for CI/CD and Teams Environments

This is where things usually break if you’re not careful.

Headless Emulator Configuration

In CI, always run the emulator in headless mode:

emulator -avd Pixel_API_34 -no-window -no-audio -no-boot-anim

Why:

• Reduces resource usage
• Improves startup time
• Avoids GPU dependency issues

This reduces overhead and avoids GPU-related issues in CI.

Avoid Snapshots in CI

Snapshots make runs inconsistent.

• Always use a clean start
• Prefer cold boot

Consistency matters more than startup time in pipelines.

Resource Limits

If you’re running multiple emulators:

• Stick to 2 cores and ~2 GB RAM per instance
• Avoid running heavy builds on the same machine at the same time

Otherwise, performance becomes unpredictable.

Storage Still Matters

Run the emulator on an SSD.

You’ll notice faster:

• Boot times
• App installs
• General responsiveness

On HDDs, even a well-configured setup will feel slow.

Internal Storage vs Expanded Storage

This part is easy to overlook, but it matters depending on what you’re testing.

Internal Storage (Data Partition):

• Used by apps for installs, cache, databases
• Affects app install speed and runtime behavior

Expanded Storage (SD Card):

• Simulates external storage
• Used for media, file access, downloads

What to do in practice:

• Keep internal storage reasonable (2–6 GB) for most dev work
• Increase this only if you frequently install large apps or test media-heavy use cases.
• Use expanded storage only if your app relies on file APIs, media handling, or scoped storage.

Why this matters: Over-allocating storage doesn’t improve performance. It just increases disk usage and snapshot size.

For most workflows, default values are fine unless you have a specific need.

Kotlin Example: Detecting Emulator

Sometimes you want to adjust behavior when running on an emulator.

fun isProbablyEmulator(): Boolean {
    val fingerprint = android.os.Build.FINGERPRINT.lowercase()
    val model = android.os.Build.MODEL.lowercase()
    val manufacturer = android.os.Build.MANUFACTURER.lowercase()
    val brand = android.os.Build.BRAND.lowercase()
    val device = android.os.Build.DEVICE.lowercase()

    return (fingerprint.startsWith("generic") ||
        fingerprint.contains("vbox") ||
        model.contains("emulator") ||
        manufacturer.contains("genymotion") ||
        (brand.startsWith("generic") && device.startsWith("generic")))
}

When to Use This

This works for:

• Debug toggles
• Logging changes
• Small performance adjustments

Don’t use it for anything security-related. It’s not reliable enough.

Common Pitfalls in Real Projects

These show up often in production teams:

• Over-allocating CPU/RAM and slowing the host
• Relying entirely on emulators instead of real devices
• Using snapshots in automated testing
• Ignoring host machine constraints
• Running multiple heavy processes alongside the emulator

What This Guide Doesn’t Replace

Even with perfect Android Emulator Settings, you still need:

Real Device Testing

Emulators don’t fully replicate:

• Thermal throttling
• OEM customizations
• Real GPU behavior

Performance Profiling

Use tools like:

• Android Profiler
• Systrace
• Frame timing metrics

Tuning without measurement is guesswork.

Test Strategy

A solid setup includes:

• Emulator for fast iteration
• Real devices for validation
• Cloud testing (e.g., device farms) for scale

A Reliable Baseline Configuration

If you want something that works in most environments:

• CPU: 2 cores
• RAM: 2–4 GB
• Graphics: Hardware (GLES 2.0/3.0)
• System Image: x86_64 (or ARM on Apple Silicon)
• Storage: SSD
• Boot Mode: Use Quick Boot for development and Cold Boot for CI.

This setup prioritizes stability over raw speed.

FAQs

What are the best Android Emulator settings in 2026?

Use hardware acceleration, x86_64 (or ARM on Apple Silicon), 2–4 GB RAM, and hardware GPU rendering.

How many CPU cores should I use?

Start with 2. Increase only if you actually need more.

Is Quick Boot safe?

Fine for development. For testing or CI, use cold boot.

Do I still need real devices?

Yes. Emulators don’t fully match real-world behavior.

Conclusion

There’s no perfect configuration that works for every setup.

The goal is simple: keep your system responsive and your emulator predictable.

Once your Android Emulator Settings are in a good place, you’ll spend less time waiting and more time building.

AI-powered coding assistants have completely changed how Android developers write code. Features like Gemini in Android Studio read your project files, understand your codebase structure, and suggest intelligent completions. That’s incredibly helpful — but it also raises an important question:

What exactly is the AI reading?

The answer is often “more than you think.” Configuration files, API keys stored in local .properties files, internal endpoint URLs, analytics tokens — all of these can end up in the AI’s context window if you’re not careful.

That’s exactly where the .aiexclude file comes in. It’s Android Studio’s answer to the .gitignore file, but instead of telling Git what to ignore, it tells the AI assistant what files should stay completely off-limits.

In this guide, we’ll walk you through everything you need to know about the .aiexclude file — what it is, why it matters, how to create and configure it, and real-world patterns to protect your project.

What Is the .aiexclude File?

The .aiexclude file is a plain text configuration file that tells Android Studio’s AI features which files and folders it should never index, read, or use as context when generating suggestions.

Think of it like a privacy wall between your sensitive project files and the AI. When a file is listed in the .aiexclude file, it simply becomes invisible to the AI — it won’t factor into any code completions, refactoring suggestions, or AI-assisted search results.

This feature was introduced as developers started using AI assistants more deeply in their workflows and needed a simple, declarative way to control what data gets shared.

Why Does This Matter?

Here’s a realistic scenario: You’re building a fintech app. You have a local.properties file with a Stripe API key sitting in your project root. Your .gitignore already excludes it from version control. But your AI assistant doesn’t know about .gitignore — it reads every file it can find in your project.

Without a .aiexclude file, that API key could end up in the AI’s context. With one, you can ensure it’s never touched.

Where to Place the .aiexclude File

The .aiexclude file can live in two places, and the location determines its scope:

1. Project root directory — Applies rules across the entire project.

MyAndroidApp/
├── .aiexclude          ← covers the whole project
├── app/
│   └── src/
├── local.properties
└── build.gradle

2. Inside a specific module or subdirectory — Applies rules only to that folder and its contents.

MyAndroidApp/
├── app/
│   ├── .aiexclude      ← covers only the /app module
│   └── src/
└── secrets/
    ├── .aiexclude      ← covers only /secrets
    └── api_keys.txt

You can even have multiple .aiexclude files in the same project, one per folder, with each one managing its own exclusion rules. They all work together, so there’s no conflict — Android Studio respects all of them.

How the .aiexclude File Syntax Works

The .aiexclude file uses a simple pattern syntax, very similar to .gitignore. Let’s break it down.

Basic File Exclusion

To exclude a specific file, just write its name or path:

# Exclude a specific file in the same directory
local.properties

# Exclude a file using a relative path
config/secrets.json

The # character starts a comment — anything after # on that line is ignored by the parser.

Excluding Entire Directories

Add a trailing slash / to target a whole folder:

# Exclude the entire secrets folder
secrets/

# Exclude a nested folder
app/src/main/assets/private/

Every file inside that folder — regardless of name or extension — becomes invisible to the AI.

Wildcard Patterns

Wildcards are your best friends here. The .aiexclude file supports standard glob patterns:

# Exclude all .properties files anywhere in the project
**/*.properties

# Exclude all JSON files in the config directory
config/*.json

# Exclude all files that start with "key_"
**/key_*

# Exclude everything inside any folder named "internal"
**/internal/**

The ** pattern means “match any number of directories,” so **/*.env would catch .env files no matter how deeply nested they are.

Negation with !

You can un-exclude something that was already covered by a broader rule, using !:

# Exclude all .properties files
**/*.properties

# ...but allow gradle.properties back in (it has no secrets)
!gradle.properties

Just like .gitignore, order matters here — later rules override earlier ones. So always put the negation after the broader exclusion.

Creating Your First .aiexclude File

Let’s walk through setting up a .aiexclude file from scratch in a typical Android project.

Step 1: Create the File

Right-click the project root in Android Studio’s Project view, select New → File, and name it exactly:

.aiexclude

No extension. No prefix. Just .aiexclude.

Tip: If you’re on Windows and File Explorer is hiding files starting with a dot, use Android Studio’s built-in file creation — it handles this correctly.

Step 2: Add Your Exclusion Rules

Open the newly created .aiexclude file and start adding your rules. Here’s a practical starter template:

# ─────────────────────────────────────────────
# .aiexclude — AI context exclusion rules
# Keeps sensitive and irrelevant files out of
# Android Studio's AI assistant context.
# ─────────────────────────────────────────────

# Local configuration with API keys or secrets
local.properties
*.env
*.env.*

# Keystores and signing credentials
**/*.jks
**/*.keystore
keystore.properties

# Service account and OAuth credential files
google-services-staging.json
**/credentials/
**/service_account*.json

# Internal analytics or experiment configs
**/internal_experiments/
**/ab_test_config.json

# Build outputs - not useful for AI context
build/
**/build/
.gradle/

# Auto-generated files (reduce AI noise)
**/generated/
**/*Generated.java
**/*Generated.kt

# Raw data or large asset files
**/raw/
**/*.csv
**/*.sqlite
**/*.db

# Private documentation
docs/internal/
INTERNAL_NOTES.md

Step 3: Verify It’s Working

After saving the .aiexclude file, restart Android Studio or invalidate caches (File → Invalidate Caches / Restart). The AI assistant should now skip the excluded files entirely when generating suggestions.

You can confirm this by checking whether the AI references any content from an excluded file — it shouldn’t.

Real-World Use Cases: What to Exclude and Why

Here are common scenarios where the .aiexclude file becomes genuinely essential.

Use Case 1: Protecting API Keys in local.properties

The local.properties file is the most common place Android developers store sensitive keys — Maps API keys, Firebase project IDs, payment gateway tokens. It’s excluded from Git, but not from AI by default.

# .aiexclude

# Keep the AI away from local config with secrets
local.properties
keystore.properties

Why this matters: If the AI reads local.properties, it might include your API key in a generated code snippet or log statement — even innocently, in a test file it suggests.

Use Case 2: Excluding Generated Code

Generated files (like Room database implementations, Hilt component files, or proto-generated classes) create a lot of noise for the AI. The AI might try to “help” by referencing or modifying them, even though they’re auto-generated and will be overwritten on the next build.

# .aiexclude

# Auto-generated files - don't waste AI context on these
**/generated/
**/*_Impl.kt
**/*.pb.java

Generated files can confuse the AI or cause it to suggest changes to code that isn’t meant to be manually edited. Excluding them improves suggestion quality.

Use Case 3: Excluding Proprietary Business Logic

Maybe you’re working on a module that contains proprietary algorithms or confidential business logic — something your company doesn’t want indexed anywhere outside of approved systems.

# .aiexclude placed inside /pricing-engine module

# Protect proprietary pricing logic from AI indexing
algorithms/
models/pricing/

Even if you trust the AI tool itself, having strict boundaries on what it accesses is good security hygiene — especially in regulated industries.

Use Case 4: Large Files That Hurt Performance

The AI doesn’t need to read a 50MB SQLite database file or a massive CSV dataset. Including them wastes AI context budget and can slow things down.

# .aiexclude

# Large files that don't help the AI at all
**/*.sqlite
**/*.db
**/*.csv
assets/large_dataset.json

AI context windows have limits. Keeping them focused on actual source code means better, more relevant suggestions.

Common Mistakes to Avoid with the .aiexclude File

Even experienced developers make these slip-ups when first working with the .aiexclude file. Here’s what to watch out for.

Mistake 1: Using Absolute Paths

This won’t work as expected:

# Absolute paths don't work
/Users/yourname/AndroidStudioProjects/MyApp/local.properties

Always use relative paths from the location of the .aiexclude file itself:

# Correct — relative path
local.properties

Mistake 2: Forgetting Subdirectories

This only excludes secrets.json at the root level:

# Only matches root-level file
secrets.json

If the file might exist deeper in the project:

# Matches the file anywhere in the project
**/secrets.json

Mistake 3: Not Committing the .aiexclude File to Version Control

Unlike local.properties, the .aiexclude file itself is not sensitive — it just describes what’s sensitive. You should absolutely commit it to Git so your whole team benefits from the same exclusion rules.

git add .aiexclude
git commit -m "Add .aiexclude to protect sensitive files from AI context"

Mistake 4: Over-Excluding Everything

It can be tempting to exclude huge chunks of your project “just to be safe,” but that defeats the purpose of the AI assistant. If the AI can’t see your code, it can’t help you write better code.

Be selective. Exclude what’s genuinely sensitive or noisy — not everything.

The .aiexclude File vs. .gitignore: What’s the Difference?

People often ask whether these two files overlap. Here’s a clear side-by-side comparison:

They’re complementary, not replacements for each other. A file can be in .gitignore but still readable by the AI — that’s the exact problem the .aiexclude file solves.

Team Workflow: Making .aiexclude a Team Standard

If you’re leading a team, the .aiexclude file should be part of your project setup checklist — right alongside .gitignore and EditorConfig.

Here’s how to make it a team standard:

Add it to your project template. If your team uses a custom Android project template (or a cookiecutter script), bake in a sensible default .aiexclude file from day one.

Include it in your code review checklist. When a new secret, config, or sensitive module gets added to the project, verify the .aiexclude file is updated accordingly.

Document it in your README. A single line in your project’s README explaining that the project uses a .aiexclude file helps new team members understand the setup quickly.

Treat it like a security document. Additions to the .aiexclude file should go through a quick review — just like changes to SECURITY.md or secrets management configs.

Advanced Pattern: Module-Level .aiexclude Files

In larger, multi-module Android projects, it often makes more sense to manage exclusions at the module level rather than maintaining one giant .aiexclude file at the root.

MyAndroidApp/
├── .aiexclude                    ← project-wide rules
├── app/
│   ├── .aiexclude                ← app module rules
│   └── src/
├── feature-payments/
│   ├── .aiexclude                ← payment module rules (strictest)
│   └── src/
└── feature-onboarding/
    └── src/

Project-root .aiexclude:

# Global rules
local.properties
**/*.jks
**/*.keystore
**/build/

feature-payments/.aiexclude:

# Extra-strict for this module — payment logic is proprietary
src/

This hierarchical approach gives you fine-grained control without cluttering a single file.

Frequently Asked Questions About the .aiexclude File

Q: Does the .aiexclude file affect code completion outside of AI features?

No. The .aiexclude file only affects the AI assistant. Standard IntelliJ code completion, navigation, and refactoring tools are not impacted.

Q: Can I use the .aiexclude file in other JetBrains IDEs?

The .aiexclude file was introduced in the context of Android Studio’s AI integration. Support in other JetBrains IDEs may vary — check the documentation for the specific IDE.

Q: What happens if I have conflicting rules between two .aiexclude files?

Each .aiexclude file applies to its own directory and below. There’s no true “conflict” — rules from parent and child directories stack together. The most specific rule (closest to the file) generally wins, similar to .gitignore behavior.

Q: Will the .aiexclude file protect me from ALL data leakage?

The .aiexclude file is a strong first line of defense for local AI features in Android Studio. However, it does not control what happens when you use external AI tools, paste code into chat interfaces, or use other plugins. Treat it as one layer of a broader security practice.

Q: Should I exclude google-services.json?

It depends. The google-services.json that goes into your app usually contains project IDs and API keys. While it’s not as sensitive as a private key, it’s worth excluding it from AI context — especially the production variant. You might do this:

# .aiexclude
google-services.json
app/google-services.json

Quick Reference: Recommended Default .aiexclude Template

Copy this into any Android project and customize as needed:

# ─────────────────────────────────────
# .aiexclude — Recommended Default
# Android Studio AI Context Exclusions
# ─────────────────────────────────────

# Secrets and local config
local.properties
keystore.properties
*.env
*.env.*
.env.local

# Signing keystores
**/*.jks
**/*.keystore

# Firebase and Google service files
google-services.json
GoogleService-Info.plist

# Service accounts and credentials
**/credentials/
**/service_account*.json

# Build artifacts
**/build/
.gradle/
**/.gradle/

# Auto-generated code
**/generated/
**/*Generated.java
**/*Generated.kt
**/*_Impl.kt

# Large binary or data assets
**/*.sqlite
**/*.db
**/*.csv
**/*.parquet

# Internal documentation
docs/internal/
INTERNAL*.md
CONFIDENTIAL*

# IDE-specific artifacts
.idea/workspace.xml
.idea/tasks.xm

Conclusion

The .aiexclude file is a small file with a big impact. In just a few lines, it lets you control exactly what your AI assistant sees — keeping sensitive keys, proprietary logic, and noisy generated files out of its context while letting it focus on the code that actually matters.

Here’s a quick recap of what we covered:

• The .aiexclude file acts like a privacy filter between your project and the AI assistant in Android Studio.
• Place it in your project root for global rules, or in subdirectories for module-level control.
• It uses glob-style patterns very similar to .gitignore.
• Always commit it to version control so your whole team benefits.
• Combine it with other security practices — it’s one layer, not a complete solution.

If you haven’t added a .aiexclude file to your Android project yet, now’s the time. Open Android Studio, create the file, drop in the template above, and customize it for your project’s needs. 

It takes five minutes and pays dividends in security, performance, and peace of mind.

If you build Android apps, you’ve probably seen the term ABI in Android at least once. It shows up in Gradle settings, Play Console warnings, and NDK documentation.

But what does it actually mean? And why does it affect your APK size and app performance?

Let’s break it down.

What Is ABI in Android?

ABI stands for Application Binary Interface.

In simple words, ABI in Android defines how your app’s compiled native code interacts with the device’s processor and operating system.

Think of it as a contract between:

• Your compiled native code (.so files)
• The Android operating system
• The device’s CPU architecture

If the ABI doesn’t match the device’s CPU, your app won’t run.

Why Does ABI Exist in Android?

Android devices use different CPU architectures. The most common ones are:

• arm64-v8a (64-bit ARM)
• armeabi-v7a (32-bit ARM)
• x86
• x86_64

Each architecture understands machine code differently. So if your app includes native C or C++ code using the Android NDK, you must compile it separately for each ABI you want to support.

That’s where ABI in Android becomes important.

What Exactly Does an ABI Define?

An ABI specifies:

• CPU instruction set (ARM, x86, etc.)
• Register usage
• Memory alignment
• Data type sizes
• How function calls work
• How binaries are formatted

When you compile native code, the compiler uses ABI rules to generate machine code that matches the target architecture.

If you build for arm64-v8a, the generated .so file won’t work on an x86 device.

What Is a Native Library in Android?

If your project uses C or C++ (via the NDK), it generates files like this:

libnative-lib.so

These are placed inside your APK under:

lib/arm64-v8a/
lib/armeabi-v7a/
lib/x86/

Each folder corresponds to a specific ABI in Android.

The system loads the correct library at runtime based on the device’s architecture.

Why ABI in Android Matters for APK Size

This is where many developers make mistakes.

If you include all ABIs in a single APK, your app contains multiple versions of the same native library.

For example:

• 5 MB for arm64
• 4 MB for armeabi-v7a
• 6 MB for x86

Now your APK suddenly includes 15 MB of native code, even though a device only needs one version.

That increases:

• Download size
• Install time
• Storage usage

Solution: Split APKs by ABI

You can configure Gradle to generate separate APKs per ABI.

Here’s an example:

// build.gradle (Module level)
android {
    splits {
        abi {
            enable true
            reset() // Clear the default list
            include "arm64-v8a", "armeabi-v7a", "x86", "x86_64"
            universalApk false // Don't generate a fat universal APK
        }
    }
}

• enable true → Turns on ABI splitting
• include → Specifies which ABIs to build
• universalApk false → Prevents creating a large APK with all ABIs

Now each device downloads only the version it needs.

This reduces APK size significantly.

What About Android App Bundles (AAB)?

If you’re using Android App Bundles (which is required for Play Store apps), Google Play automatically delivers the correct native libraries per device.

This is called ABI split delivery.

In this case, you don’t need manual split configuration for Play Store distribution.

However, understanding ABI in Android still matters when:

• Testing locally
• Distributing outside Play Store
• Debugging native crashes
• Optimizing build size

How ABI in Android Affects Performance

Performance impact comes from two main areas:

1. 32-bit vs 64-bit

Modern devices use arm64-v8a. Running a 64-bit native library provides:

• Better memory handling
• More CPU registers
• Improved performance for heavy computation
• Better compatibility with modern Android versions

Google Play requires 64-bit support for apps using native code.

If you ship only 32-bit libraries, your app may run in compatibility mode on 64-bit devices. That’s not ideal.

2. CPU-Specific Optimization

When you compile for a specific ABI in Android, the compiler generates instructions optimized for that architecture.

Example:

• ARM CPUs use ARM instruction sets
• x86 devices use Intel instruction sets

Native code compiled for ARM won’t run efficiently on x86 without translation.

Better ABI targeting = better runtime performance.

How to Specify ABI in Android (NDK Example)

If you use CMake, you can define supported ABIs like this:

android {
    defaultConfig {
        ndk {
            abiFilters "arm64-v8a", "armeabi-v7a"
        }
    }
}

• abiFilters restricts which ABIs are built
• Prevents generating unnecessary .so files
• Reduces build time
• Reduces final APK size

Simple but powerful.

How to Check Device ABI

You can check the device ABI programmatically:

val abiList = Build.SUPPORTED_ABIS
for (abi in abiList) {
    Log.d("ABI_CHECK", abi)
}

This returns a list like:

arm64-v8a
armeabi-v7a

The first ABI is the preferred one.

Common Mistakes Developers Make

Including Too Many ABIs

If your analytics show 95% ARM users, shipping x86 may not be worth it unless you need emulator support.

Not Supporting 64-bit

Google Play requires 64-bit native support for apps using the NDK.

Using Universal APKs in Production

Universal APKs contain all ABIs. That’s convenient for testing, but inefficient for production distribution.

Best Practices for ABI in Android

Here’s a practical checklist:

• Always support arm64-v8a
• Include armeabi-v7a if you still support older devices
• Avoid x86 unless required
• Use Android App Bundles for Play distribution
• Use abiFilters to control builds
• Monitor APK size regularly
• Test native crashes per architecture

When Should You Care About ABI in Android?

You should care if:

• You use the Android NDK
• You integrate native SDKs (camera, ML, gaming engines)
• You want to reduce APK size
• You optimize performance
• You publish on Google Play

If your app is pure Kotlin or Java without native libraries, ABI doesn’t directly affect you.

Real-World Example

Let’s say you’re building a photo editing app with native image processing in C++.

If you:

• Ship only 32-bit libraries
• Include all ABIs in one APK
• Don’t optimize build filters

Your APK may grow from 25 MB to 60 MB.

But if you:

• Use ABI splits
• Support only ARM architectures
• Use App Bundles

You can reduce the download size significantly while improving performance on modern devices.

That’s the practical impact of understanding ABI in Android.

Conclusion

ABI in Android is not just a technical term buried in documentation. It directly affects:

• APK size
• App performance
• Play Store compliance
• User experience

If your app includes native code, ABI decisions matter a lot.

Keep your builds clean. Support 64-bit. Ship only what users need.

And most importantly, understand what’s inside your APK.

That’s how you build lean, fast, production-ready Android apps.