Developers

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:

/data/adb/modules/$MODID
module.prop module metadata (required) system/ merged into /system at boot (unless skip_mount exists) zygisk/ Zygisk libraries: arm64-v8a.so, armeabi-v7a.so, riscv64.so, x86.so, x86_64.so post-fs-data.sh runs in post-fs-data mode service.sh runs in late_start service mode uninstall.sh runs when Magisk removes the module action.sh runs when the user taps the module's Action button system.prop properties loaded with resetprop sepolicy.rule extra SELinux policy statements skip_mount / disable / remove status flag files

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:

module.prop
id=example_module name=Example Module version=v1.0 versionCode=1 author=you description=What this module does # optional: updateJson=https://example.com/update.json
  • id must match ^[a-zA-Z][a-zA-Z0-9._-]+$ (so a_module and module-101 work; 1_module and a module don't) and should never change once published.
  • versionCode must 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).
  • updateJson points to a JSON file with version, versionCode, zipUrl and changelog, so the Magisk app can offer updates.

Boot scripts: post-fs-data vs service

post-fs-datalate_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.
WhenBefore modules are mounted and before zygote startsLater in boot
Use forOnly what must happen before mountingAlmost everything (recommended)
Watch outsetprop 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 .replace file in it (or list it in REPLACE in customize.sh).
  • To remove a file or folder, create a dummy character device at the same path: mknod GoogleCamera c 0 0 inside $MODDIR/system/app, or list the path in REMOVE in customize.sh.
  • For /vendor, /product and /system_ext, use system/vendor, system/product and system/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.

Zip a module from inside its folder
$cd example_module && zip -r ../example_module.zip . $adb push ../example_module.zip /sdcard/Download/

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 exit in customize.sh. Use abort, so the installer can clean up.
  • Use ui_print, not echo, 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 latest module_installer.sh.
  • Set SKIPUNZIP=1 if 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. 1onLoadIn the freshly forked process; keep api and env
  2. 2preAppSpecializeZygote's privileges: companion, module dir, change args
  3. 3Android specializesApp UID, SELinux context and sandbox applied
  4. 4postAppSpecializeInside the app's sandbox
  5. 5Zygisk unloadsAPI calls stop working; your library stays unless you asked for dlclose
From the comments in Magisk's Zygisk API header (zygisk.hpp, API version 5) and zygisk/module.cpp at v31.1.

Callbacks you override

Method of zygisk::ModuleBaseWhen 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 / postServerSpecializeThe same pair for system_server, with ServerSpecializeArgs.

Api methods

MethodWhat it doesWhere 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

APIMinimum MagiskWhat changed
v527.0 (27000)Adds mount_sysprop_overrides to AppSpecializeArgs; documents the SELinux requirement for getModuleDir
v426.0 (26000)Adds exemptFd; pltHookRegister takes dev/inode instead of a regex; pltHookExclude removed
v324.3 (24300)New fields in AppSpecializeArgs
v224.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.

module/jni/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

  1. 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 libcxx is one.
  2. Keep the sample's Application.mk settings: APP_STL := none, C++17, no exceptions or RTTI, hidden visibility. The README says not to use the NDK's C++ STL; link the bundled libcxx instead, or the system libstdc++ if you only need new. It asks for NDK r21 or newer.
  3. Run ndk-build in the module folder (or open the project in Android Studio). Libraries appear in libs/<abi>/lib<name>.so.
  4. 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 accepts riscv64.so, but the sample's APP_ABI doesn't build it by default.
  5. Zip the module with its module.prop, install it from the Magisk app's Modules tab, make sure Zygisk is on, and reboot.
Build and check the log
$git clone --recurse-submodules https://github.com/YOU/your-zygisk-module.git $cd your-zygisk-module/module && ndk-build $adb logcat -s MyModule

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.

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