Magisk and Zygisk module development
Everything you need to write a first Magisk module: the folder layout, the strict module.prop format, boot scripts, the installer, and, for native code, the Zygisk API with a minimal module you can build. Magisk's developer guide and the Zygisk header are the reference; this page collects them in one place and adds the details that trip people up.
Last updated 7 sourcesHow we check pages
Module layout
An installed module is a folder in /data/adb/modules, named after the module's ID. Only module.prop is required:
Do not create the vendor, product or system_ext symlinks yourself. Magisk generates them. Any other files and folders are allowed. How Magisk applies the system/ folder at boot is explained in how modules are applied.
module.prop
The format is strict:
idmust match^[a-zA-Z][a-zA-Z0-9._-]+$(soa_moduleandmodule-101work;1_moduleanda moduledon't) and should never change once published.versionCodemust be an integer. It is used to compare versions.- Every other value is a single line of text. Use Unix (LF) line endings, not Windows (CR+LF).
updateJsonpoints to a JSON file withversion,versionCode,zipUrlandchangelog, so the Magisk app can offer updates.
Boot scripts: post-fs-data vs service
| post-fs-data | late_start service | |
|---|---|---|
| Blocking? | Yes. Boot waits until the scripts finish or 40 seconds pass; Magisk's v31.1 guide adds that the scripts are capped at 35 seconds so it still has time to mount modules. | No. Runs in parallel with boot. |
| When | Before modules are mounted and before zygote starts | Later in boot |
| Use for | Only what must happen before mounting | Almost everything (recommended) |
| Watch out | setprop deadlocks boot here. Use resetprop -n. | To wait for boot to complete: resetprop -w sys.boot_completed 0 |
Inside scripts, use MODDIR=${0%/*} rather than hardcoding the module path. ZYGISK_ENABLED is set to 1 when Zygisk is on. All scripts run in Magisk's BusyBox ash shell in "standalone mode", so commands such as ls always resolve to BusyBox applets; call a full path such as /system/bin/ls to bypass that. resetprop has the property commands.
An action.sh script adds an Action button to the module's card; tapping it runs the script in the app's console with BOOTMODE=true (since v31.0, a built-in terminal). Magisk also runs "general scripts" from /data/adb/post-fs-data.d and /data/adb/service.d if they are executable, but its guide says modules should not add any during installation.
Replacing and removing system files
- Files in the module's
system/folder are merged into/system: existing files are replaced, new files are added. - To replace a whole folder instead of merging, put an empty
.replacefile in it (or list it inREPLACEincustomize.sh). - To remove a file or folder, create a dummy character device at the same path:
mknod GoogleCamera c 0 0inside$MODDIR/system/app, or list the path inREMOVEincustomize.sh. - For
/vendor,/productand/system_ext, usesystem/vendor,system/productandsystem/system_ext. Magisk handles where those partitions really are. - Extra SELinux rules go in
sepolicy.rule, one magiskpolicy statement per line.
The installer zip and customize.sh
The simplest installer is the module folder zipped, with module.prop at the top level of the zip (not inside a subfolder; otherwise installation stops with "This zip is not a Magisk module!"). Recovery flashing additionally needs META-INF/com/google/android/update-binary (a copy of Magisk's module_installer.sh) and an updater-script containing only #MAGISK.
An optional customize.sh is sourced (not executed) after files are extracted and default permissions are set. It can read MAGISK_VER, MAGISK_VER_CODE, BOOTMODE, MODPATH, TMPDIR, ZIPFILE, ARCH (arm, arm64, x86, x64 or riscv64), IS64BIT and API, and use ui_print, abort, set_perm and set_perm_recursive (default context u:object_r:system_file:s0).
- Do not call
exitincustomize.sh. Useabort, so the installer can clean up. - Use
ui_print, notecho, or the text won't show in a custom recovery. - Do not include a file named
install.sh. - Do not put custom logic in
update-binary. The Magisk app replaces it with the latestmodule_installer.sh. - Set
SKIPUNZIP=1if you want to handle extraction yourself.
The Zygisk API
A Zygisk module is a native library that Zygisk loads into app processes as they are created. The whole API is one self-documented header, zygisk.hpp, in the official Zygisk module sample. The current version is ZYGISK_API_VERSION 5, the same in Magisk v30.7, v31.0 and v31.1. The header is released under 0BSD, so it places no licence conditions on your module.
A Zygisk module's life in one app process
- 1
onLoadIn the freshly forked process; keepapiandenv - 2
preAppSpecializeZygote's privileges: companion, module dir, change args - 3Android specializesApp UID, SELinux context and sandbox applied
- 4
postAppSpecializeInside the app's sandbox - 5Zygisk unloadsAPI calls stop working; your library stays unless you asked for
dlclose
Callbacks you override
Method of zygisk::ModuleBase | When and with what privileges |
|---|---|
onLoad(Api *api, JNIEnv *env) | First call after the module is loaded into the new process. Store both pointers. |
preAppSpecialize(AppSpecializeArgs *args) | Before the app is sandboxed, with zygote's privileges. You can read and change the arguments (uid, nice_name, app_data_dir and more). |
postAppSpecialize(const AppSpecializeArgs *args) | After specialization, inside the app's sandbox. |
preServerSpecialize / postServerSpecialize | The same pair for system_server, with ServerSpecializeArgs. |
Api methods
| Method | What it does | Where it works |
|---|---|---|
connectCompanion() | Returns a socket to your root companion process (registered with REGISTER_ZYGISK_COMPANION), or -1. The companion matches the caller's 32- or 64-bit ABI. | pre*Specialize only |
getModuleDir() | File descriptor of your module's folder, or -1. The folder must be readable by zygote (for example system_file context). | pre*Specialize only |
setOption(Option) | FORCE_DENYLIST_UNMOUNT: unmount Magisk and module files for this process whatever the DenyList says. DLCLOSE_MODULE_LIBRARY: unload your library after post*Specialize; never set it after hooking anything. | Unmount option in preAppSpecialize |
getFlags() | PROCESS_GRANTED_ROOT (the user granted this app root) and PROCESS_ON_DENYLIST. | Any callback |
exemptFd(int fd) | Stops zygote from closing a file descriptor you opened. Added in API v4. | preAppSpecialize |
hookJniNativeMethods(env, className, methods, n) | Replaces registered JNI native methods; the originals are written back into each fnPtr (or nullptr if not found). | Any callback |
pltHookRegister(dev, inode, symbol, newFunc, oldFunc) and pltHookCommit() | PLT hooks on a loaded ELF, identified by the dev and inode pair from /proc/self/maps (API v4 replaced the old regex form). | Any callback |
All API methods stop working after post*Specialize, because Zygisk unloads itself from the process. Your code never runs as real root: pre* callbacks have zygote's privileges and post* callbacks the app's. Put anything that needs root in the companion. Note that with Enforce DenyList on, Magisk's built-in Zygisk loads no modules at all into processes on the DenyList.
API versions
| API | Minimum Magisk | What changed |
|---|---|---|
| v5 | 27.0 (27000) | Adds mount_sysprop_overrides to AppSpecializeArgs; documents the SELinux requirement for getModuleDir |
| v4 | 26.0 (26000) | Adds exemptFd; pltHookRegister takes dev/inode instead of a regex; pltHookExclude removed |
| v3 | 24.3 (24300) | New fields in AppSpecializeArgs |
| v2 | 24.0 (24000) | First public API |
The sample's README says Magisk will always load modules built for an older API, so you can stay on an older header if you don't need the newer features. Standalone implementations (Zygisk Next, ReZygisk, NeoZygisk) implement the same API, but check each one's README for the version it supports.
A minimal Zygisk module
This logs the name of every app process it is loaded into, then asks Zygisk to unload it, since it hooks nothing. It is a trimmed version of the sample's example.cpp.
#include <android/log.h>
#include "zygisk.hpp"
#define LOGD(...) __android_log_print(ANDROID_LOG_DEBUG, "MyModule", __VA_ARGS__)
class MyModule : public zygisk::ModuleBase {
public:
void onLoad(zygisk::Api *api, JNIEnv *env) override {
this->api = api;
this->env = env;
}
void preAppSpecialize(zygisk::AppSpecializeArgs *args) override {
const char *process = env->GetStringUTFChars(args->nice_name, nullptr);
LOGD("loaded into %s", process);
env->ReleaseStringUTFChars(args->nice_name, process);
// Nothing hooked, so let Zygisk dlclose this library afterwards
api->setOption(zygisk::Option::DLCLOSE_MODULE_LIBRARY);
}
private:
zygisk::Api *api;
JNIEnv *env;
};
REGISTER_ZYGISK_MODULE(MyModule)Building and packaging
- Create your project from the sample with GitHub's Use this template button or a clone (the README asks you not to fork it). Clone with submodules, because the bundled
libcxxis one. - Keep the sample's
Application.mksettings:APP_STL := none, C++17, no exceptions or RTTI, hidden visibility. The README says not to use the NDK's C++ STL; link the bundledlibcxxinstead, or the systemlibstdc++if you only neednew. It asks for NDK r21 or newer. - Run
ndk-buildin themodulefolder (or open the project in Android Studio). Libraries appear inlibs/<abi>/lib<name>.so. - Copy each library into your module's
zygisk/folder, renamed to its ABI:arm64-v8a.so,armeabi-v7a.so,x86.so,x86_64.so. Magisk also acceptsriscv64.so, but the sample'sAPP_ABIdoesn't build it by default. - Zip the module with its
module.prop, install it from the Magisk app's Modules tab, make sure Zygisk is on, and reboot.
If the Modules tab shows "Zygisk module not loaded due to incompatibility", Magisk has created zygisk/unloaded: usually a missing library for the phone's ABI or a library built against the wrong header. Fix it and reinstall. Magisk deletes the unloaded marker at each boot and creates it again only if loading still fails.
Testing safely
- Keep USB debugging on with your computer approved, so a module that breaks boot can be removed with
adb wait-for-device shell magisk --remove-modules. See fixing a Magisk bootloop. - A crash in
pre*code takes zygote down with it. Magisk stops loading Zygisk after zygote crashes more than three times in one boot, and its automatic Safe Mode disables all modules after two failed boots. - Test on more than one Android version and both with and without the target app on the DenyList. Before publishing, read how users install modules in the module catalog.
Sources
This page is written from the sources below. If anything here disagrees with them, the upstream source is correct.
- Magisk developer guide (topjohnwu)
- module_installer.sh (topjohnwu/Magisk)
- Zygisk module sample: README, API version table, build setup (topjohnwu)
- Zygisk API header zygisk.hpp, API version 5 (topjohnwu)
- Magisk source: Zygisk API header at v31.1, zygisk/api.hpp (topjohnwu)
- Magisk source: module loading and DenyList, zygisk/module.cpp (topjohnwu)
- Magisk changelog: Zygisk API versions (topjohnwu)
Found a mistake or something out of date? Tell us and we will check it against the source and fix the page. Confirmed corrections are listed in the corrections log.
Report a problem with this page