INSTALL_FAILED_NO_MATCHING_ABIS means the APK contains native libraries (.so files) that were compiled for a CPU architecture the target device or emulator does not support. The fix is to either include the correct ABI in your build configuration or create an emulator image that matches the ABIs your APK ships. This error only affects apps that use native code (NDK, C/C++ libraries, or third-party SDKs with native components). Pure Java/Kotlin apps without native libraries will never trigger it.

What Are ABIs in Android?

ABI stands for Application Binary Interface. It defines how compiled native code interacts with the operating system at the machine code level. Different CPU architectures require different compiled binaries because their instruction sets are incompatible.

Android supports four primary ABIs:

When an APK contains native libraries, Android checks whether the APK includes .so files for the device's ABI. If no matching library exists, installation fails with INSTALL_FAILED_NO_MATCHING_ABIS.

Why This Error Happens

The most common scenario is running an APK built only for ARM on an x86 emulator (or vice versa). Here is the typical sequence:

1. Your app depends on a native library (e.g., SQLCipher, OpenCV, FFmpeg, or a Firebase SDK with native components).
2. Your build configuration only includes ARM ABIs.
3. You try to install the APK on an x86_64 emulator.
4. The emulator cannot find x86_64 .so files in the APK.
5. Installation fails with INSTALL_FAILED_NO_MATCHING_ABIS.

You can verify your device's ABI with:

adb shell getprop ro.product.cpu.abi

Output example:

x86_64

And inspect which ABIs your APK contains:

1# Using aapt (from Android SDK build-tools)
2aapt dump badging app-debug.apk | grep native-code
3
4# Or unzip and check directory structure
5unzip -l app-debug.apk | grep "lib/"

Expected output for an APK with multiple ABIs:

1lib/armeabi-v7a/libnative.so
2lib/arm64-v8a/libnative.so
3lib/x86/libnative.so
4lib/x86_64/libnative.so

If the output shows only lib/arm64-v8a/ but your emulator is x86_64, that explains the failure.

Fix 1: Include All Required ABIs in build.gradle

The most straightforward fix is configuring your build to include native libraries for every target ABI:

1android {
2    defaultConfig {
3        ndk {
4            abiFilters 'armeabi-v7a', 'arm64-v8a', 'x86', 'x86_64'
5        }
6    }
7}

After adding this, rebuild the APK:

./gradlew assembleDebug

This ensures the APK contains .so files for all four major architectures. The trade-off is a larger APK size since it bundles four copies of every native library.

Targeting specific ABIs

If you only deploy to specific device types, you can narrow the filter:

1android {
2    defaultConfig {
3        ndk {
4            // Only ARM devices (most physical phones)
5            abiFilters 'armeabi-v7a', 'arm64-v8a'
6        }
7    }
8}

This produces a smaller APK but will fail on x86 emulators. Use this when you ship to physical devices only and test on ARM emulator images.

Fix 2: Use an Emulator Image That Matches Your APK

Instead of changing the build, you can create an emulator that supports the ABIs your APK already contains.

In Android Studio:

1. Open Tools > Device Manager.
2. Click Create Virtual Device.
3. Select a device definition (e.g., Pixel 7).
4. On the system image screen, choose an image that matches your APK's ABI.

For ARM APKs on Apple Silicon Macs (M1/M2/M3), select an arm64-v8a system image. These run natively without translation and avoid the ABI mismatch entirely.

For Intel/AMD machines, select an x86_64 image and make sure your APK includes x86_64 libraries.

1# List available emulator images
2sdkmanager --list | grep "system-images"
3
4# Install a specific ARM64 image
5sdkmanager "system-images;android-34;google_apis;arm64-v8a"

Fix 3: Use APK Splits to Generate Per-ABI APKs

APK splits produce separate APKs for each architecture, keeping each one small while covering all target devices:

1android {
2    splits {
3        abi {
4            enable true
5            reset()
6            include 'armeabi-v7a', 'arm64-v8a', 'x86', 'x86_64'
7            universalApk true  // also create a fat APK as fallback
8        }
9    }
10}

This generates files like:

1app-armeabi-v7a-debug.apk    (smallest, ARM 32-bit only)
2app-arm64-v8a-debug.apk      (ARM 64-bit only)
3app-x86-debug.apk            (Intel 32-bit only)
4app-x86_64-debug.apk         (Intel 64-bit only)
5app-universal-debug.apk      (all ABIs, largest)

Install the correct split for your target:

1# For an x86_64 emulator
2adb install app-x86_64-debug.apk
3
4# For a physical ARM64 device
5adb install app-arm64-v8a-debug.apk

For Google Play distribution, use Android App Bundles (AAB) instead of APK splits. Play Store handles per-device delivery automatically.

Fix 4: Use Android App Bundle (AAB) for Distribution

App Bundles let Google Play generate optimized APKs for each device configuration, including ABI:

1android {
2    defaultConfig {
3        ndk {
4            abiFilters 'armeabi-v7a', 'arm64-v8a', 'x86', 'x86_64'
5        }
6    }
7}

./gradlew bundleRelease

Upload the .aab file to Google Play Console. The Play Store generates and serves device-specific APKs, so each user downloads only the native libraries their device needs.

For local testing of App Bundles, use bundletool:

1# Generate APKs from the bundle
2bundletool build-apks --bundle=app-release.aab --output=app.apks
3
4# Install on a connected device
5bundletool install-apks --apks=app.apks

Special Case: Apple Silicon Macs and ARM Emulators

On M1/M2/M3 Macs, the Android emulator runs ARM system images natively because the host CPU is ARM-based. This means:

• ARM APKs install and run without issues.
• x86 APKs fail with INSTALL_FAILED_NO_MATCHING_ABIS because the emulator does not translate x86 instructions.

If you encounter this error on Apple Silicon:

1. Verify your emulator uses an arm64-v8a system image.
2. Ensure your APK includes arm64-v8a in its ABI filters.
3. If using third-party SDKs, confirm they ship ARM64 native libraries.

Diagnosing the Error Systematically

When you encounter INSTALL_FAILED_NO_MATCHING_ABIS, follow this checklist:

1# Step 1: Check the device/emulator ABI
2adb shell getprop ro.product.cpu.abi
3adb shell getprop ro.product.cpu.abilist
4
5# Step 2: Check what ABIs the APK contains
6unzip -l app-debug.apk | grep "\.so$"
7
8# Step 3: Compare - is there overlap?
9# If not, either add the missing ABI to your build or change the emulator image

The ro.product.cpu.abilist property shows all ABIs the device supports, including compatibility layers. An ARM64 device typically supports both arm64-v8a and armeabi-v7a.

Common Pitfalls

Building only for ARM and testing on an x86 emulator. This is the most frequent cause. Either add x86/x86_64 to your abiFilters or switch to an ARM emulator image.

Assuming the error means a corrupt APK. The APK is fine. The problem is a mismatch between the native libraries it contains and the device's CPU architecture.

Including all ABIs in release builds without splits or bundles. Bundling four copies of native libraries inflates APK size significantly. Use APK splits or App Bundles for production to keep download sizes small.

Forgetting that third-party SDKs bring their own native libraries. Even if your own code is pure Kotlin, a dependency like react-native, flutter, or realm may include .so files for only certain ABIs.

Using x86 emulator images on Apple Silicon Macs. The ARM-based host cannot run x86 emulator images efficiently. Use arm64-v8a images instead. This is the reverse of the traditional problem.

Not checking ro.product.cpu.abilist for compatibility. A device might support multiple ABIs through compatibility layers. An ARM64 device can usually run ARMv7 code, so armeabi-v7a libraries may work even without a dedicated arm64-v8a build.

Summary

• INSTALL_FAILED_NO_MATCHING_ABIS means the APK's native libraries do not match the target device's CPU architecture.
• Add the required ABIs to ndk.abiFilters in build.gradle and rebuild.
• Alternatively, create an emulator image that matches your APK's existing ABIs.
• Use APK splits or Android App Bundles to distribute architecture-specific APKs without inflating download size.
• On Apple Silicon Macs, use arm64-v8a emulator images and ensure your APK includes ARM64 native libraries.
• Always verify both the device ABI (adb shell getprop ro.product.cpu.abi) and the APK contents (unzip -l or aapt dump) when diagnosing this error.