Convert Figma logo to code with AI

RikkaApps logoShizuku

Using system APIs directly with adb/root privileges from normal apps through a Java process started with app_process.

10,677
626
10,677
142

Top Related Projects

47,030

The Magic Mask for Android

17,465

LSPosed Framework

7,410

The native part of the Xposed framework (mainly the modified app_process binary).

Example code for "How-To SU"

Quick Overview

Shizuku is an Android app and development framework that provides a way for other apps to use system APIs without root access. It achieves this by running a Java process with ADB or root permissions, allowing apps to perform system-level operations through IPC (Inter-Process Communication).

Pros

  • Enables apps to access system APIs without requiring root access
  • Improves battery life and performance by reducing the need for separate root processes
  • Provides a secure way for apps to perform system-level operations
  • Supports both ADB and root methods for initialization

Cons

  • Requires initial setup using ADB or root, which may be challenging for some users
  • Limited to Android devices and not applicable to other platforms
  • May pose security risks if misused or if malicious apps gain access to Shizuku's capabilities
  • Requires ongoing maintenance to keep up with Android system changes

Code Examples

  1. Checking if Shizuku is available and requesting permission:
if (Shizuku.pingBinder()) {
    if (Shizuku.checkSelfPermission() == PackageManager.PERMISSION_GRANTED) {
        // Shizuku is available and permission is granted
    } else if (Shizuku.shouldShowRequestPermissionRationale()) {
        // Show rationale for requesting permission
    } else {
        // Request permission
        Shizuku.requestPermission(SHIZUKU_PERMISSION_REQUEST_CODE)
    }
} else {
    // Shizuku is not available
}
  1. Executing a shell command using Shizuku:
val result = Shizuku.newProcess(arrayOf("sh", "-c", "ls /system"), null, null).waitFor()
println("Exit code: $result")
  1. Creating a UserService using Shizuku:
class MyUserService : IUserService.Stub() {
    override fun destroy() {
        // Clean up resources
    }

    override fun doSomething() {
        // Perform some system-level operation
    }
}

Shizuku.bindUserService(
    UserServiceArgs(ComponentName(context, MyUserService::class.java)),
    object : ServiceConnection {
        override fun onServiceConnected(name: ComponentName, service: IBinder) {
            val userService = IUserService.Stub.asInterface(service)
            userService.doSomething()
        }

        override fun onServiceDisconnected(name: ComponentName) {
            // Handle disconnection
        }
    }
)

Getting Started

  1. Add the Shizuku dependency to your app's build.gradle:
dependencies {
    implementation 'dev.rikka.shizuku:api:12.1.0'
}
  1. Initialize Shizuku in your app's main activity:
override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    Shizuku.addBinderReceivedListener(binderReceivedListener)
    Shizuku.addBinderDeadListener(binderDeadListener)
    if (Shizuku.isPreV11()) {
        // Handle pre-v11 initialization
    }
}
  1. Request permission and handle the result:
private fun requestShizukuPermission() {
    if (Shizuku.checkSelfPermission() == PackageManager.PERMISSION_GRANTED) {
        // Permission already granted
    } else {
        Shizuku.requestPermission(SHIZUKU_PERMISSION_REQUEST_CODE)
    }
}

override fun onRequestPermissionsResult(requestCode: Int, permissions: Array<out String>, grantResults: IntArray) {
    when (requestCode) {
        SHIZUKU_PERMISSION_REQUEST_CODE -> {
            if (grantResults.isNotEmpty() && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
                // Permission granted, proceed with Shizuku operations
            } else {
                // Permission denied, handle accordingly
            }
        }
    }
}

Competitor Comparisons

47,030

The Magic Mask for Android

Pros of Magisk

  • Provides root access and system-level modifications
  • Offers a wide range of modules for customization
  • Supports systemless modifications, preserving system integrity

Cons of Magisk

  • Requires unlocking the bootloader, which may void warranty
  • Higher risk of security vulnerabilities due to root access
  • More complex setup process compared to Shizuku

Code Comparison

Magisk (C++):

static int magisk_main(int argc, char *argv[]) {
    if (argc > 1 && strcmp(argv[1], "-c") == 0) {
        printf(MAGISK_VERSION ":MAGISK\n");
        return 0;
    }
    // ...
}

Shizuku (Java):

public class ShizukuProvider extends ContentProvider {
    @Override
    public boolean onCreate() {
        ShizukuProvider.init(getContext());
        return true;
    }
    // ...
}

Magisk focuses on low-level system modifications using C++, while Shizuku provides a Java-based API for app permissions and system interactions. Magisk's code deals with version checking and command-line arguments, whereas Shizuku's code initializes a ContentProvider for app communication.

17,465

LSPosed Framework

Pros of LSPosed

  • More comprehensive system-level modifications
  • Supports a wider range of Android versions
  • Larger community and more extensive module ecosystem

Cons of LSPosed

  • Requires more complex setup and root access
  • Higher risk of system instability if not used carefully
  • May void device warranty or trigger SafetyNet checks

Code Comparison

LSPosed typically involves more complex code for system-level hooks:

@ArtMethod("com.android.server.pm.PackageManagerService->getApplicationInfo")
public class PackageManagerServiceHook {
    public ApplicationInfo hook(ApplicationInfo originalInfo) {
        // Modify application info
        return modifiedInfo;
    }
}

Shizuku often uses simpler API calls for app-level modifications:

ShizukuBinderWrapper binder = new ShizukuBinderWrapper(IBinder.FIRST_CALL_TRANSACTION) {
    @Override
    protected Bundle run() throws RemoteException {
        // Perform privileged operations
        return result;
    }
};

Both projects aim to enhance Android functionality, but LSPosed focuses on system-wide modifications, while Shizuku provides a more controlled approach for specific app enhancements.

Pros of XposedInstaller

  • More established and widely used in the Android modding community
  • Offers a broader range of system-level modifications
  • Supports a vast ecosystem of Xposed modules

Cons of XposedInstaller

  • Requires rooting the device, which can void warranties and compromise security
  • May cause system instability or compatibility issues with certain apps
  • Development has slowed down in recent years

Code Comparison

XposedInstaller (Java):

public class XposedApp extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        XposedBridge.initXposed(this);
    }
}

Shizuku (Kotlin):

class ShizukuApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        Shizuku.initialize(this)
    }
}

Both projects aim to provide enhanced functionality for Android devices, but they take different approaches. XposedInstaller is a more traditional framework that requires root access and modifies the system at a deeper level. Shizuku, on the other hand, focuses on providing elevated permissions to apps without requiring root, making it a safer and more user-friendly option for many users.

While XposedInstaller offers more extensive customization options, Shizuku provides a balance between functionality and system integrity. The code comparison shows that both projects have similar initialization processes, but Shizuku's use of Kotlin reflects its more modern development approach.

7,410

The native part of the Xposed framework (mainly the modified app_process binary).

Pros of Xposed

  • More established and widely adopted in the Android modding community
  • Supports a broader range of Android versions and devices
  • Offers deeper system-level modifications and hooks

Cons of Xposed

  • Requires device rooting and system modification
  • Can potentially cause system instability or security vulnerabilities
  • Development has slowed down in recent years

Code Comparison

Xposed module implementation:

public class MyXposedModule implements IXposedHookLoadPackage {
    public void handleLoadPackage(LoadPackageParam lpparam) throws Throwable {
        XposedHelpers.findAndHookMethod("com.example.app.MainActivity", lpparam.classLoader,
            "onCreate", Bundle.class, new XC_MethodHook() {
                @Override
                protected void beforeHookedMethod(MethodHookParam param) throws Throwable {
                    // Modification logic here
                }
            });
    }
}

Shizuku implementation:

public class MyShizukuService extends IMyAidlInterface.Stub {
    @Override
    public void doSomething() {
        // Privileged operation logic here
    }
}

// In your app
ShizukuBinderWrapper wrapper = new ShizukuBinderWrapper(new MyShizukuService());
IMyAidlInterface service = IMyAidlInterface.Stub.asInterface(wrapper);
service.doSomething();

While Xposed focuses on system-wide method hooking, Shizuku provides a framework for running privileged operations through a service, offering a different approach to extending app functionality on Android devices.

Example code for "How-To SU"

Pros of libsuperuser

  • Lightweight and focused on root access functionality
  • Well-established and widely used in the Android development community
  • Simple implementation for basic root operations

Cons of libsuperuser

  • Limited scope compared to Shizuku's broader feature set
  • Less active development and updates
  • May require more manual handling of root permissions

Code Comparison

Shizuku (Java):

@SystemService
IPackageManager getPackageManager() {
    return IPackageManager.Stub.asInterface(
        Shizuku.getBinder(Context.PACKAGE_SERVICE));
}

libsuperuser (Java):

Shell.SU.run("pm list packages");

Shizuku provides a more integrated approach to accessing system services, while libsuperuser focuses on executing shell commands with root privileges. Shizuku offers a higher level of abstraction and potentially safer access to system functionalities, whereas libsuperuser provides a more direct but potentially riskier method of executing root commands.

Both libraries serve different purposes and cater to different use cases in Android development. Shizuku is more suitable for apps requiring extensive system integration, while libsuperuser is better for simpler root-based operations.

Convert Figma logo designs to code with AI

Visual Copilot

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Shizuku

Background

When developing apps that requires root, the most common method is to run some commands in the su shell. For example, there is an app that uses the pm enable/disable command to enable/disable components.

This method has very big disadvantages:

  1. Extremely slow (Multiple process creation)
  2. Needs to process texts (Super unreliable)
  3. The possibility is limited to available commands
  4. Even if ADB has sufficient permissions, the app requires root privileges to run

Shizuku uses a completely different way. See detailed description below.

User guide & Download

https://shizuku.rikka.app/

How does Shizuku work?

First, we need to talk about how app use system APIs. For example, if the app wants to get installed apps, we all know we should use PackageManager#getInstalledPackages(). This is actually an interprocess communication (IPC) process of the app process and system server process, just the Android framework did the inner works for us.

Android uses binder to do this type of IPC. Binder allows the server-side to learn the uid and pid of the client-side, so that the system server can check if the app has the permission to do the operation.

Usually, if there is a "manager" (e.g., PackageManager) for apps to use, there should be a "service" (e.g., PackageManagerService) in the system server process. We can simply think if the app holds the binder of the "service", it can communicate with the "service". The app process will receive binders of system services on start.

Shizuku guides users to run a process, Shizuku server, with root or ADB first. When the app starts, the binder to Shizuku server will also be sent to the app.

The most important feature Shizuku provides is something like be a middle man to receive requests from the app, sent them to the system server, and send back the results. You can see the transactRemote method in rikka.shizuku.server.ShizukuService class, and moe.shizuku.api.ShizukuBinderWrapper class for the detail.

So, we reached our goal, to use system APIs with higher permission. And to the app, it is almost identical to the use of system APIs directly.

Developer guide

API & sample

https://github.com/RikkaApps/Shizuku-API

Migrating from pre-v11

Existing applications still works, of course.

https://github.com/RikkaApps/Shizuku-API#migration-guide-for-existing-applications-use-shizuku-pre-v11

Attention

  1. ADB permissions are limited

    ADB has limited permissions and different on various system versions. You can see permissions granted to ADB here.

    Before calling the API, you can use ShizukuService#getUid to check if Shizuku is running user ADB, or use ShizukuService#checkPermission to check if the server has sufficient permissions.

  2. Hidden API limitation from Android 9

    As of Android 9, the usage of the hidden APIs is limited for normal apps. Please use other methods (such as https://github.com/LSPosed/AndroidHiddenApiBypass).

  3. Android 8.0 & ADB

    At present, the way Shizuku service gets the app process is to combine IActivityManager#registerProcessObserver and IActivityManager#registerUidObserver (26+) to ensure that the app process will be sent when the app starts. However, on API 26, ADB lacks permissions to use registerUidObserver, so if you need to use Shizuku in a process that might not be started by an Activity, it is recommended to trigger the send binder by starting a transparent activity.

  4. Direct use of transactRemote requires attention

    • The API may be different under different Android versions, please be sure to check it carefully. Also, the android.app.IActivityManager has the aidl form in API 26 and later, and android.app.IActivityManager$Stub exists only on API 26.

    • SystemServiceHelper.getTransactionCode may not get the correct transaction code, such as android.content.pm.IPackageManager$Stub.TRANSACTION_getInstalledPackages does not exist on API 25 and there is android.content.pm.IPackageManager$Stub.TRANSACTION_getInstalledPackages_47 (this situation has been dealt with, but it is not excluded that there may be other circumstances). This problem is not encountered with the ShizukuBinderWrapper method.

Developing Shizuku itself

Build

  • Clone with git clone --recurse-submodules
  • Run gradle task :manager:assembleDebug or :manager:assembleRelease

The :manager:assembleDebug task generates a debuggable server. You can attach a debugger to shizuku_server to debug the server. Be aware that, in Android Studio, "Run/Debug configurations" - "Always install with package manager" should be checked, so that the server will use the latest code.

License

The code for this project is available under the Apache-2.0 license.

Exceptions

  • You are FORBIDDEN to use image files listed below in any way (unless for displaying Shizuku itself).

    manager/src/main/res/mipmap-hdpi/ic_launcher.png
    manager/src/main/res/mipmap-hdpi/ic_launcher_background.png
    manager/src/main/res/mipmap-hdpi/ic_launcher_foreground.png
    manager/src/main/res/mipmap-xhdpi/ic_launcher.png
    manager/src/main/res/mipmap-xhdpi/ic_launcher_background.png
    manager/src/main/res/mipmap-xhdpi/ic_launcher_foreground.png
    manager/src/main/res/mipmap-xxhdpi/ic_launcher.png
    manager/src/main/res/mipmap-xxhdpi/ic_launcher_background.png
    manager/src/main/res/mipmap-xxhdpi/ic_launcher_foreground.png
    manager/src/main/res/mipmap-xxxhdpi/ic_launcher.png
    manager/src/main/res/mipmap-xxxhdpi/ic_launcher_background.png
    manager/src/main/res/mipmap-xxxhdpi/ic_launcher_foreground.png
    
  • For the project as a whole, it is not free. You are FORBIDDEN to distribute the apk compiled by you (including modified, e.g., rename app name "Shizuku" to something else) to any store (IBNLT Google Play Store, F-Droid, Amazon Appstore etc.).