Skip to main content

Fix 'INSTALL_FAILED_USER_RESTRICTED' via USB Debugging on MIUI

 You compile your project in Android Studio, the Gradle build completes successfully, but deployment halts immediately. Instead of your application launching on your connected device, the Run window throws a fatal error: Installation did not succeed. The application could not be installed: INSTALL_FAILED_USER_RESTRICTED.

This error disproportionately affects developers using Xiaomi, Redmi, or POCO devices. While standard Android Open Source Project (AOSP) builds allow unrestricted ADB installations once developer options are active, Xiaomi’s heavily modified operating system (MIUI and the newer HyperOS) imposes strict, proprietary security layers that intercept standard deployment workflows.

Here is the exact technical breakdown of why this happens and how to configure your Xiaomi device for reliable Android app testing.

Understanding the Root Cause: Why MIUI Blocks ADB Installs

When you initiate a deployment from Android Studio, the IDE utilizes the Android Debug Bridge (ADB) to push your compiled APK to the device's /data/local/tmp/ directory. It then invokes the device's internal PackageManager service to execute the installation.

Under the hood, Android Studio issues a command similar to this:

adb shell pm install -t -r -g "/data/local/tmp/com.yourcompany.app.apk"
  • -t: Allows installation of test APKs (APKs built with android:testOnly="true").
  • -r: Replaces the existing application.
  • -g: Grants all runtime permissions automatically.

On a Pixel or Samsung device, the standard PackageManager accepts this request and installs the app. On a Xiaomi device, the system's proprietary "Security" app intercepts the IPC (Inter-Process Communication) call to the PackageManager.

MIUI categorizes silent ADB installations as high-security risks. Unless the device explicitly authorizes the host machine through Xiaomi's specific validation checks, the OS forcibly rejects the installation, returning the INSTALL_FAILED_USER_RESTRICTED status code to the ADB daemon.

The Fix: Configuring Your Xiaomi Device for Android App Testing

To resolve this deployment failure, you must bypass MIUI's interception layer. This requires enabling a specific combination of developer settings that go beyond standard Android Studio USB debugging.

Step 1: Enable Core Developer Options

If you have not already exposed the developer menu:

  1. Navigate to Settings > About phone.
  2. Tap on the MIUI version (or OS version) entry exactly 7 times.
  3. A toast message will confirm, "You are now a developer!"

Step 2: Configure USB Debugging and Security Settings

Navigate to Settings > Additional settings > Developer options. You must enable three specific toggles in this exact order:

  1. USB debugging: Enable this to allow the ADB daemon to connect.
  2. Install via USB: Enable this to allow apps to be installed via ADB. Note: Xiaomi requires an active SIM card and a registered Xiaomi Account logged into the device to toggle this switch.
  3. USB debugging (Security settings): Enable this to allow ADB to grant permissions and simulate input. This is required for Android Studio to attach the debugger and handle the -g installation flag.

Step 3: The Critical Step — MIUI Optimization Disable

Even with the above settings enabled, MIUI's memory management and UI rendering engine can still interfere with the test APK installation process. A complete MIUI optimization disable is often mandatory.

Xiaomi frequently hides this toggle in modern MIUI versions. To reveal and disable it:

  1. Scroll to the very bottom of the Developer options menu.
  2. Locate the Autofill section.
  3. Find the option labeled Reset to default values.
  4. Tap Reset to default values rapidly 5 to 7 times.
  5. A new toggle labeled Turn on MIUI optimization will appear at the bottom of the screen.
  6. Toggle this setting to Off.
  7. A highly restrictive warning prompt will appear. Wait the mandatory 5 seconds and tap Accept.

Once disabled, reboot your device to ensure the standard AOSP PackageManager behaviors are fully restored. Reconnect your device, verify the RSA key fingerprint prompt if it appears, and run your project from Android Studio. The INSTALL_FAILED_USER_RESTRICTED error will be resolved.

Deep Dive: The Mechanics of ADB Deployment

When you disable MIUI optimization, you are not just changing UI behaviors; you are fundamentally altering how the Android framework allocates resources and handles application lifecycles on the device.

MIUI optimization aggressively kills background processes and implements proprietary view rendering to conserve battery. By turning it off, you force the device to fallback to standard AOSP behaviors.

If you want to manually verify your device's package manager policies without relying on Android Studio's UI, you can run an installation via the terminal. Use the following command to check for verbose error outputs during standard Android app testing:

# Push the APK to the temporary directory
adb push app/build/outputs/apk/debug/app-debug.apk /data/local/tmp/

# Attempt a manual installation with verbose output
adb shell pm install --user 0 -t -r -g /data/local/tmp/app-debug.apk

If the installation succeeds here but fails in Android Studio, your issue lies within your Run/Debug Configurations in the IDE, not the device policy.

Common Pitfalls and Edge Cases

The SIM Card Requirement

Xiaomi actively blocks developers from enabling the Install via USB toggle unless a physical SIM card is inserted into the device and connected to the cellular network. If you are using a Wi-Fi-only testing device, you must temporarily insert a valid SIM card, bind your Xiaomi account, enable the toggle, and then you may remove the SIM card. The setting will persist.

Device Reboots Resetting Permissions

After a system OTA (Over-The-Air) update, MIUI frequently resets the USB debugging (Security settings) toggle back to its default disabled state. If deployments suddenly start failing with the restricted error after months of success, check this toggle first.

Gradle Properties Workaround (Test-Only Flag)

In rare cases on HyperOS, stripping the test-only flag from the APK can bypass the restriction without disabling MIUI Optimization. You can force Android Studio to build a standard release-style APK for debug builds by modifying your gradle.properties file:

# Add this to your project's gradle.properties
android.injected.testOnly=false

Warning: Using this property alters the deployment behavior and can prevent Android Studio from automatically launching the main activity after installation. Use this strictly as a fallback if the device settings fail.

Conclusion

The INSTALL_FAILED_USER_RESTRICTED error is an intended security feature by Xiaomi, not a bug in your code or your IDE. By properly configuring Android Studio USB debugging, registering a Xiaomi account to authorize ADB installations, and executing a complete MIUI optimization disable, you bridge the gap between AOSP standards and OEM modifications, ensuring a stable, predictable environment for Android app testing.

Labels: