Introduction

Shizuku-API is the client-side library and developer guide for Shizuku and Sui. It lets an Android app execute its own Java or JNI code under the identity of ADB shell (UID 2000) or root (UID 0), instead of being limited to the app's own sandbox permissions.

Two mechanisms are exposed:

• Remote binder call through rikka.shizuku.ShizukuBinderWrapper, which forwards Binder calls to a Shizuku service running with elevated privilege. It is simple but only covers what Binder calls can do, so it suits small features.
• UserService, a bound-service-like component that runs in a separate process as root or shell. It allows arbitrary Java/native code and has no non-SDK API restrictions, though it is not a normal Android app process, so many Context APIs (for example registerReceiver or getContentResolver) do not work.

The project targets Android developers who need privileged operations such as package management, system settings, or shell commands, and who are prepared to read Android framework source. Per the guide, developing against these APIs is closer to framework or system-app development than ordinary app development, so familiarity with cs.android.com and hidden API behavior is valuable.

Quick Start

Prerequisites: Android 6.0+, a user device with Shizuku or Sui installed, and a project using Android Gradle. On non-rooted devices Shizuku must be started through adb after each boot (wireless debugging works on Android 11+); on rooted devices Sui is a Magisk module that requires an unlocked bootloader. Users can download Shizuku from the official download page or install Sui from Magisk or the Sui repository.

1. Add the dependencies, using the current Maven Central version in place of the placeholder:

def shizuku_version = "<version from Maven Central>"
implementation "dev.rikka.shizuku:api:$shizuku_version"
// Required only if you support Shizuku (not just Sui)
implementation "dev.rikka.shizuku:provider:$shizuku_version"

2. Register ShizukuProvider in AndroidManifest.xml (needed for Shizuku; from v12.1.0 it also initializes Sui automatically):

<provider
    android:name="rikka.shizuku.ShizukuProvider"
    android:authorities="${applicationId}.shizuku"
    android:multiprocess="false"
    android:enabled="true"
    android:exported="true"
    android:permission="android.permission.INTERACT_ACROSS_USERS_FULL" />

3. Add a binder listener via Shizuku.addBinderReceivedListener() and Shizuku.addBinderDeadListener(), and only call Shizuku methods while the binder is alive, otherwise an IllegalStateException is thrown. For Sui, call Sui.init(packageName) before using Shizuku; this only needs to run once per process, and it can be called on the main thread.

4. Request permission in the style of Android runtime permissions using Shizuku.checkSelfPermission(), Shizuku.requestPermission(code), and Shizuku.addRequestPermissionResultListener(). Pre-v11 Shizuku is unsupported.

5. Start using the privilege. For a simple binder call, use ShizukuBinderWrapper. To run your own code, implement a class extending your AIDL Stub and start it with Shizuku.bindUserService(UserServiceArgs, ServiceConnection); stop it with unbindUserService, and implement the destroy transaction (16777115, or 16777114 in aidl) to clean up and call System.exit(), because the process is not killed automatically.

A complete demo project is included. When debugging UserService, enable "Always install with package manager" in Android Studio's Run/Debug configurations so the latest code is used.

Usage Constraints

• The privilege backend matters: Shizuku#getUid() returns 0 for root and 2000 for ADB. What ADB can do depends on the Android permissions granted to Shell, which change across Android versions, and shell cannot access other apps' data directories such as /data/user/0/<package>.
• The UserService process is not a valid Android application process; even with a Context, APIs like registerReceiver and getContentResolver will not work.
• Multi-process apps must call ShizukuProvider.enableMultiProcessSupport() in every process that uses the API, and Sui.init() in every such process.
• For remote binder calls to hidden APIs, the app process still needs a bypass such as AndroidHiddenApiBypass; the HiddenApiRefinePlugin helps with compile-time hidden API access.
• Version requirements: since 13.1.0, apps with min API 23 must enable library desugaring; pre-v11 Shizuku support was dropped in 12.1.0; and UserServiceArgs.tag should be set explicitly because ProGuard/R8 can rename class names, and matching on class name is unstable.
• Shizuku#newProcess is slated for removal; migrate to UserService.
• The project is MIT licensed. Users must install Shizuku or Sui separately; the API alone does nothing.

HotRepo's take

On the Java daily list for 2026-11-01, Shizuku-API was recorded at position 6 with 2,724 stars and 1,297 forks, a gain of 6 stars that day. The near 1:2 fork-to-star ratio is notable: many developers appear to clone the project to study or adapt it rather than just star it, which fits a library whose demo and guide are the main entry points. That single snapshot only describes that day; it does not establish a longer-term trend. The project's practical barrier is not installation but understanding Android privilege semantics, as the guide itself warns that ordinary app development experience may not be enough.