What is NPatch

NPatch is a rootless Xposed framework powered by the Vector core.

It's a modern Xposed module injection and app patching tool designed for rootless environments. NPatch injects an Xposed loader into APK files without requiring Root: Local mode pairs with the Manager to dynamically load and manage modules and scopes (the Manager does not need to stay running in the background); Integrated mode embeds modules directly into the target app for standalone operation on devices without the Manager.

The core submodule points to HSSkyBoy/Vector — the runtime core that powers all of NPatch's capabilities.

How It Works

The patching process roughly:

1. Opens the target APK with apkzlib
2. Rewrites AndroidManifest.xml, replacing appComponentFactory with top.nkbe.npatch.metaloader.LSPAppComponentFactoryStub
3. Injects the meta-loader dex (assets/npatch/metaloader.dex)
4. In both modes, embeds loader dex and libnpatch.so (arm64-v8a and x86_64) in the patched APK, so bootstrap never depends on reading the Manager APK
5. When signature bypass level ≥ Basic, embeds the original APK as a nested zip (assets/npatch/origin.apk) so the original signature can be read at runtime
6. Re-signs with a keystore, outputting <original-name>-<NPatch versionCode>-npatched.apk

At runtime, the rewritten appComponentFactory bootstraps the Xposed environment on demand, then delegates component creation to the app's original factory. A bootstrap failure is recorded in cache/npatch/bootstrap_state.json; NPatch then tries to let the original app continue instead of crashing it with a static-initializer error.

The version number in the output filename suffix is NPatch's own LSConfig.VERSION_CODE, not the original APK's versionCode.

Module APIs and Runtime Capabilities

NPatch uses one Vector runtime for different module generations instead of shipping a separate wrapper dex for each API version:

• Legacy modules continue to support traditional assets/xposed_init and XSharedPreferences
• Modern modules support libxposed API 101 and API 102 lifecycles
• Single-entry API 102 modules can opt into hot reload, with explicit success and failure results
• Legacy, API 101, and API 102 share the NPatch Remote data layer; Remote Preferences support writes, deletion, and change callbacks, while Remote Files support listing, opening, and deletion

Two Patching Modes

NPatch has two mutually exclusive patching modes:

• Local Mode (--manager): Modules and scopes remain configured by the Manager. Startup prefers the Manager Binder, falls back to its ConfigProvider, and may use the last successfully synchronized module cache. Adding or removing modules and synchronizing Remote data still requires the Manager.
• Integrated Mode (--embed): Patches apps with modules built in. Patched apps run independently without the Manager but cannot dynamically manage configuration. Ideal for devices without NPatch Manager.

The two flags are mutually exclusive on CLI. See Local & Integrated Modes for details.

System Requirements

• Android 9 (API 28) or higher
• Upper bound roughly matches JingMatrix/Vector
• Patching tool: jar-v<verName>-<verCode>-release.jar (pure Java, cross-platform — runs on Windows / macOS / Linux, requires Java)

Good For

• Devices without unlocked bootloader, or where Root is unwanted/impossible
• Injecting Xposed modules into specific user apps only
• Distributing the same patched APK across multiple devices

Not Good For

• Modifying system server, framework, or system apps — NPatch only handles user apps
• Apps with strong integrity checks, SafetyNet / Play Integrity strict verification (e.g., banking apps, some games)
• Hardened APKs (dex encryption, packer protection) — usually cannot be patched directly

Next Steps

• Get started: Usage
• Manager and Shizuku: Manager & Shizuku
• Choose a mode: Local & Integrated Modes
• Troubleshooting: FAQ