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: GitHub Actions on the open-source branch
• Debug builds: GitHub Actions only
• Official channel: Telegram

Filename Format

Release filenames look like:

jar-v1.0.5-639-release.jar
manager-v1.0.5-639-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 manager-v1.0.5-639-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.

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.

java -jar jar-v1.0.5-639-release.jar [options] <apks...>

Minimal example (Local mode, default Basic signature bypass):

java -jar jar-v1.0.5-639-release.jar --manager target.apk

Integrated mode (embed one or more modules):

java -jar jar-v1.0.5-639-release.jar --embed module1.apk --embed module2.apk target.apk

Examples below use jar-v1.0.5-639-release.jar as the filename — substitute with whichever version you downloaded.

CLI Options

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

Option	Description	Default
<apks>	APK paths to patch (positional, at least one)	—
-h, --help	Show help	—
-o, --output	Output directory	. (current dir)
-f, --force	Overwrite existing output	off
-p, --newpackage	Patch with a new package name	unchanged
-d, --debuggable	Mark app as debuggable	off
-l, --sigbypasslv	Signature bypass level 0–4 (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	Output Xposed and framework boot logs to Media directory	on
-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	off
-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) and Seccomp (4) 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)

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

Installing Patched 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
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 and you're done. Modules are already at assets/npatch/modules/<package>.apk. To change modules, re-patch.

Custom Keystore

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

java -jar jar-v1.0.5-639-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 V2 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.