FAQ

General

How does NPatch compare to Magisk + LSPosed?

Completely different approaches:

• Magisk + LSPosed: Requires Root, modules operate at system level, can hook system apps and framework
• NPatch: No Root needed, can only hook individual user apps that have been patched

NPatch is not a replacement for the Magisk route. It solves the "can't Root but want Xposed modules" scenario.

Which Android versions are supported?

Minimum Android 9 (API 28). Upper bound roughly matches JingMatrix/Vector. Android 8 and below are not supported.

Can the patching tool run on Mac / Linux?

Yes. jar-v<verName>-<verCode>-release.jar is pure Java, cross-platform — just needs Java installed. The Manager is an Android APK.

---

Installation & Patching

Patched APK fails to install with "app not installed" or "signature conflict"

The original app is still installed with a different signature, and Android refuses to overlay. Uninstall the original first, then install the patched version. Make sure you've backed up your data.

Patching fails with APK parse error

Possible causes:

• The APK is a split APK (split installation) — pass all splits together, e.g., java -jar jar-v1.0.5-639-release.jar base.apk split_config.arm64_v8a.apk ...
• The APK is from an XAPK / APKM container format — extract the actual APKs first
• The APK is hardened (dex encryption, packer protection) — usually cannot be patched directly

NPatch handles split APKs specially: files starting with split_ that lack appComponentFactory take a fast path — repackaged only, no injection.

Do I have to use the built-in keystore?

No. Three choices:

• -npa — built-in NPatch keystore
• -fpa — built-in FPA keystore
• -k path storePass alias aliasPass — custom keystore

All three are mutually exclusive. If none is specified, the default behavior uses the built-in NPatch keystore. Internally loaded as BKS format with V2 signing.

What's the default signature bypass level?

1 (Basic). Change with -l 0~4 or --sigbypasslv 0~4. Note: Integrated mode (--embed) caps at 2 (High). For Extreme or Seccomp you must use --manager.

---

Modules & Runtime

Patched app installed but modules aren't working

Local mode:

1. Confirm the Manager is installed (top.nkbe.npatch)
2. In the Manager, check the module into this app's scope
3. Confirm the module itself is enabled in the Manager

Integrated mode:

1. Confirm you used --embed module.apk when patching, not --manager
2. The module must have xposed_init / assets/xposed_init, otherwise the framework won't recognize it

Add -v when re-patching, check Manager logs or logcat to see exactly which step failed.

App has signature verification, crashes or shows "signature error"

Escalate --sigbypasslv:

• Default 1 (Basic) doesn't work → try 2 (High)
• Still failing → switch to --manager and try 3 (Extreme, hooks PackageInfo(Parcel) constructor)
• Still failing → 4 (Seccomp, ARM64 seccomp v2 filtering with trusted thread file redirection, last resort)

Note: 3 and 4 require --manager — the CLI blocks them in Integrated mode. If level 4 still doesn't work, the app likely uses SafetyNet / Play Integrity hardware integrity checks, which cannot currently be bypassed. Common with banking apps and some games.

App checks installer source (Play Store install origin)

Use --installerSource to set the installer source string, e.g., --installerSource com.android.vending to simulate a Play Store installation.

What about apps using GMS?

If the device has a MicroG replacement (e.g., ReVanced GmsCore), add --useMicroG when patching. This adds fake-signature metadata and FAKE_PACKAGE_SIGNATURE permission to the manifest, redirecting com.google.android.gms calls to MicroG. Works for YouTube and other Google apps — requires installing the corresponding MicroG service separately.

Want to downgrade install (patched versionCode higher than original)

Add -r or --allowdown to force the output APK's versionCode to 1. This allows future downgrade installation and generally doesn't affect the app's perceived version number.

Browser or apps with isolated processes can't load modules

For apps that need isolated processes (e.g., browser rendering engines), add --injectdex when patching to inject the loader Dex directly into the original app package.

---

Modes

How to choose between Local and Integrated mode?

Quick guide:

• Personal use, will swap modules → Local mode
• Distributing to others / they don't have the Manager → Integrated mode
• App has hard signature checks, needs Extreme / Seccomp → Local mode only

See Local & Integrated Modes for details. See Manager & Shizuku for what else the Manager can do.

What happens if I use both --manager and --embed?

The CLI blocks it — the two flags are mutually exclusive.

What happens in Local mode without the Manager installed?

The app launches normally but no modules are loaded. It's essentially a patched-but-module-less version.

---

Other

Can patched APKs log into original accounts?

Usually yes (package name is unchanged). Apps with device binding, strong signature verification, or Play Integrity may not work — e.g., some banking apps, Tencent apps, strict-verification games.

Can I install both the original and patched version?

Not by default (same package name). To have both, use -p / --newpackage to assign a different package name, but most apps won't recognize old data and push notifications will stop working.

Where to report issues?

• Bugs: GitHub Issues
• Official channel: Telegram
• Source code: GitHub