Usage

NPatch provides two artifacts:

• jar-v<verName>-<verCode>-release.jar — Cross-platform patching tool, pure Java, runs on Windows / macOS / Linux
• manager-v<verName>-<verCode>-release.apk — Android Manager app, only needed for Local mode

Both are typically released together. Read What is NPatch first to understand the two modes, then come back here.

Download

• Stable: GitHub Releases
• Canary builds: Test versions released by developers, available on the Telegram channel
• Debug builds: Debugging versions, available only on GitHub Actions
• Official channel: Telegram

Filename Format

Release filenames look like:

jar-v<verName>-<verCode>-release.jar
manager-v<verName>-<verCode>-release.apk

Pattern: <artifact>-v<verName>-<verCode>-<variant>.{jar,apk}

• verName — Version name (e.g., 1.0.5)
• verCode — Version code (e.g., 639)
• variant — Build type: release (stable) or debug (Actions only)

Requirements

Item	Requirement
Patching tool runtime	Java
Platform	Windows / macOS / Linux
Android version	Patched apps require Android 9 (API 28)+

Two Ways to Patch

Option 1: Using the Manager App (Recommended)

Install the current manager-v<verName>-<verCode>-release.apk on your device, select the app to patch from the UI, and install the result directly — all on-device. This is the recommended approach for most users. The Manager UI defaults to High (2) signature bypass.

See Manager & Shizuku for more.

Option 2: Using the jar

Best for batch patching, automation, or CI. Feed the target APK to the jar, get <original>-<NPatch versionCode>-npatched.apk or <original>-npatched.apks.

java -jar jar-v<verName>-<verCode>-release.jar [options] <apks...>

Minimal example (Local mode; the CLI defaults to Basic signature bypass):

java -jar jar-v<verName>-<verCode>-release.jar --manager target.apk

Patching Split APKs / App Bundles (pass base and all split apks together):

java -jar jar-v<verName>-<verCode>-release.jar --manager base.apk split_config.arm64_v8a.apk split_config.zh.apk

Integrated mode (embed one or more modules):

java -jar jar-v<verName>-<verCode>-release.jar --embed module1.apk --embed module2.apk target.apk

Replace <verName> and <verCode> in the examples with the version you downloaded.

Packaging & Split APKs (APKS) Support

NPatch natively supports both standalone APKs and multi-split Split APKs / APKS / App Bundles:

• Standalone APK: Directly produces a patched, ready-to-install standalone APK.
• Split APKs / APKS:
  • Automatically identifies base.apk alongside all configuration splits (ABI, locale, screen density).
  • When changing package name (-p), overriding versionCode (-r / --allowdown), or modifying targetSdkVersion, NPatch automatically synchronizes all split manifests with the base APK to prevent package installer verification errors.
  • Split APKs are resigned and realigned without redundant core package nesting, maintaining a minimal archive size.
  • Standardized .apks archives are generated (internally structured as base.apk and split_*.apk), fully compatible with system installers, InstallLion, SAI, Shizuku, and third-party tools.

CLI Options

Corresponds to @Parameter declarations in top.nkbe.npatch.patch.NPatch.

Option	Description	Default
<apks>	APK paths to patch (positional, at least one; can pass base and all split APKs)	—
-h, --help	Show help	—
-o, --output	Output directory	. (current dir)
-f, --force	Overwrite existing output	off
-p, --newpackage	Patch with a new package name (synchronized across splits)	unchanged
-d, --debuggable	Mark app as debuggable	off
-l, --sigbypasslv	Signature bypass level 0–5 (see below)	1
--injectdex	Inject loader Dex (needed for isolated processes, e.g., browser renderers)	off
--provider	Inject file picker (from MT Manager) to manage data directory files	off
--installerSource	Set installer source string	—
--useMicroG	Enable MicroG support, redirect GMS calls to community MicroG	off
--outputLog	Write Legacy and API 101/102 module API logs, framework logs, and uncaught Java/Kotlin crashes asynchronously to the Media directory (non-blocking)	on
--hidelibs	Reduce basic environment-detection signals by sanitizing ART and sensitive system-library visibility	off
-k, --keystore	Custom keystore: path storePass alias aliasPass	—
-npa, --npatch-keystore	Use built-in NPatch keystore	—
-fpa, --fpa-keystore	Use built-in FPA keystore	—
--manager	Enable Local mode (mutually exclusive with --embed)	—
-r, --allowdown	Set output versionCode to 1, allowing future downgrades (synchronized across splits)	off
--versioncode	Set the replacement versionCode used with --allowdown	1
-v, --verbose	Verbose packaging log	off
-m, --embed	Enable Integrated mode with specified module APK, repeatable (mutually exclusive with --manager)	—

Mutual Exclusion Rules

Enforced at CLI parse time:

• --manager and --embed cannot be used together
• -k cannot be used with -npa or -fpa
• -npa and -fpa cannot be used together
• Extreme (3), Seccomp (4), and Stealth (5) require --manager; Integrated mode caps sigbypass at High (2)

Signature Bypass Levels

From NPatch's official UI descriptions:

Level	Name	Description	Available in Integrated
0	None	No processing	Yes
1	Basic	Adds Java IO and Native openat/openat64 redirection so signature-related file reads access the original APK	Yes
2	High	Based on Basic, restores original AppComponentFactory and hooks getPackageArchiveInfo, hasSigningCertificate, etc.	Yes
3	Extreme	Based on High, hooks PackageInfo(Parcel) constructor to override Binder deserialization of signature info	No (requires --manager)
4	Seccomp	Enables seccomp v2 filtering and trusted thread file redirection on ARM64, based on FunPatchApp's approach	No (requires --manager)
5	Stealth	Uses xhook to redirect app-native-library GOT/PLT entries while retaining PackageInfo signature spoofing	No (requires --manager)

In practice: start with 1, escalate if needed. Higher levels aren't always better — some apps behave worse at higher levels.

Installing Patched APKs / APKS

Since signatures differ, you must uninstall the original app first. Make sure you've backed up your data.

WARNING

Uninstalling removes app data. Back up important data from the original app first, or use ADB backup.

Local Mode: Next Steps

1. Install manager-v*-release.apk (package top.nkbe.npatch, if not already installed)
2. Install the patched APK or APKS
3. Open the Manager, find the app, add Xposed modules to its scope
4. Launch the app — modules take effect

Integrated Mode: Next Steps

Install the patched APK / APKS and you're done. Modules are already at assets/npatch/modules/<package>.apk. To change modules, re-patch.

Signature Schemes & Custom Keystore

NPatch implements full V1 (JAR Signing) + V2 (APK Signature Scheme v2) + V3 (APK Signature Scheme v3) signing schemes, dynamically resolving the target application's real minSdkVersion (auto-adaptive minSdk 21+), ensuring complete compatibility across Android OS releases and installation engines.

By default the built-in keystore is used (falls back to -npa). To use your own:

java -jar jar-v<verName>-<verCode>-release.jar -k mykey.jks storePass myalias aliasPass --manager target.apk

Four positional arguments: keystore path, store password, alias, alias password. Internally loaded as BKS format with V1 + V2 + V3 signing enabled.

The Manager also has custom keystore settings where you can verify keystore type, password, and alias.

Having Issues?

See FAQ, or ask on Telegram.