Magisk Architecture TL;DR
  • 100% Systemless Modification: Magisk intercepts early boot via magiskinit and mounts custom partitions via tmpfs bind mounts and OverlayFS without altering physical /system or /vendor blocks.
  • Universal Android Compatibility: Operates across Android 6.0 through Android 16+ on all major CPU architectures (ARM64, ARMv7, x86, x86_64, RISC-V).
  • Zygisk In-Process Hooking: Allows native C++ modules to execute code inside the Zygote process and all app sandboxes before specialization.
  • MagiskBoot Swiss Army Knife: Complete binary for unpacking, repacking, CPIO patching, DTB modifying, and hex-patching boot images (V0–V4, init_boot, vendor_boot).
  • Live SELinux Compilation: Granular policy injection via magiskpolicy prevents the security vulnerabilities of SELinux Permissive mode.
Architecture & Technical Manual

Getting Started with Magisk

Magisk is the premier open-source root and systemless customization utility for Android devices. Created by John Wu (@topjohnwu), Magisk empowers users and developers to install system-level modifications, manage superuser permissions, and inject runtime hooks into application processes without permanently modifying the device's read-only system partitions.

Independent Technical Documentation & Upstream Primary Source This portal provides independent community-maintained technical documentation, architecture deep dives, and device-specific flashing manuals. The Magisk open-source software project is created and maintained by John Wu (@topjohnwu). For official release source code and upstream developer documentation, refer directly to topjohnwu.github.io/Magisk and the official Magisk GitHub repository.

Prerequisites & Unlock Checklist

Before proceeding with Magisk installation, verify that your environment satisfies all prerequisite requirements:

  • Unlocked Bootloader: Your device bootloader must be in an unlocked state to allow flashing custom or patched boot images via Fastboot or Odin. Unlocking wipes device user data.
  • ADB and Fastboot Platform Tools: Install the latest Google Android SDK Platform-Tools on your PC.
  • Target Stock Firmware Image: Obtain a matching stock boot.img (or init_boot.img for Android 13+) corresponding to your exact build number.
  • Battery Level: Ensure your device has at least 50% battery to prevent sudden shutdowns during image flashing.

Safety Guidelines

Never Flash Another Device's Patched Image Always patch your boot image on the exact target device where Magisk will be run. Patching on another device or downloading someone else's patched image can lead to partition size mismatches, dm-verity corruption, and instant bootloops.
Home Docs Core Architecture

Core Architecture & Boot Lifecycle

Magisk's architecture is built around early boot execution hijacking, mount namespace cloning, dynamic tmpfs injection, and in-process hooking.

Android Boot Stages & Two-Stage Init (2SI)

On modern Android systems (Android 10+), the kernel mounts the ramdisk in rootfs and executes /init. Magisk replaces /init with its own magiskinit binary. The boot sequence proceeds through the following distinct stages:

1. Pre-Init (magiskinit)
Replaces /init. Mounts tmpfs to /sbin or /debug_ramdisk, extracts Magisk binaries, injects early SELinux rules, unpacks the real init, and transfers execution.
2. post-fs-data
Triggered after /data is decrypted and mounted in FBE (File-Based Encryption). Magisk daemon starts, binds /data/adb/modules into tmpfs, and executes module post-fs-data.sh scripts.
3. late_start (service)
Triggered in parallel with Android framework startup. Executes all module service.sh scripts and initializes background services.
4. boot-completed
Triggered when sys.boot_completed=1. The Magisk daemon broadcasts completion and completes any pending module update merges.

Magic Mount & OverlayFS Filesystem Layering

Magisk utilizes two primary mechanisms to modify files across /system, /vendor, and /product:

  • Kernel OverlayFS: On modern kernels supporting OverlayFS, Magisk creates an upper filesystem layer from module folders and merges them onto stock partition mount points without block modification.
  • Magic Mount (Bind Mounts): On legacy kernels or fallback modes, Magisk recursively clones directory structures into tmpfs and creates bind mounts for modified files and new nodes.

magisksu-internals">MagiskSU Daemon & Isolation

MagiskSU manages root privileges. When a client process invokes su, it communicates via a UNIX domain socket with the master Magisk daemon in /data/adb/magisk. The daemon checks permissions against /data/adb/magisk.db, prompts the user via the Magisk app UI if unconfigured, transitions the process to SELinux domain u:r:magisk:s0, and forks the requested command with uid=0.

Home Docs Installation Guide

Comprehensive Installation Methods

Depending on your device manufacturer and Android launch version, select the appropriate installation procedure below.

Method 1: Boot / Init_boot Patching via Fastboot (Recommended)

This is the standard, universal installation method for Google Pixel, Motorola, OnePlus, Xiaomi, and other modern Android devices.

Fastboot Patching Procedure
# 1. Install Magisk APK on your device $adb install -r Magisk-v30.7.apk # 2. Push stock boot.img or init_boot.img to device storage $adb push init_boot.img /sdcard/Download/ # 3. In Magisk App: Tap Install -> Select and Patch a File -> Choose image # 4. Pull the patched image back to PC $adb pull /sdcard/Download/magisk_patched_*.img patched_boot.img # 5. Reboot into Bootloader mode $adb reboot bootloader # 6. Flash to appropriate partition (init_boot for Android 13+, boot for others) $fastboot flash init_boot patched_boot.img $fastboot reboot

Method 2: Samsung Galaxy Devices (Odin AP Tar)

Samsung devices utilize proprietary download mode and do not support standard Fastboot. Magisk supports patching full Samsung AP firmware archives.

  • Download the matching stock firmware for your exact model and CSC region from official sources (SamFW / Frija).
  • Extract the firmware zip to locate the AP_[model]_[build].tar.md5 file.
  • Copy the AP file to your device, open Magisk, tap Install -> Select and Patch a File, and select the AP tar file.
  • Transfer the generated magisk_patched_[random].tar back to your computer.
  • Reboot your Samsung device into Download Mode. Open Odin on Windows, place the patched tar into the AP slot, and place the corresponding BL, CP, and CSC files into their respective slots.
  • Click Start. Once finished, boot directly into recovery to perform a factory data wipe if unlocking bootloader for the first time.

Method 3: Custom Recovery (TWRP / OrangeFox)

If you have a custom recovery installed, rename the Magisk-v30.7.apk file to Magisk-v30.7.zip. Boot into TWRP/OrangeFox and flash the zip directly, or use adb sideload Magisk-v30.7.zip.

Method 4: Seamless OTA Updates (A/B Partition Devices)

To apply system updates seamlessly without losing root or access to custom modules:

OTA Update Survival Sequence
# Step 1: In Magisk App -> Uninstall -> Restore Images (DO NOT REBOOT) # Step 2: In Android Settings -> System Update -> Download & Install OTA # Step 3: When installation completes -> DO NOT TAP REBOOT PROMPT IN SETTINGS # Step 4: Return to Magisk App -> Install -> Install to Inactive Slot (After OTA) # Step 5: Tap Reboot directly inside the Magisk App

Partition Reference Matrix

Launch Android Version Kernel Architecture Target Partition to Patch Fastboot Command
Android 13, 14, 15, 16+ GKI 2.0 (5.10, 5.15, 6.1, 6.6+) init_boot.img fastboot flash init_boot patched.img
Android 10, 11, 12 Legacy Ramdisk SAR (4.14, 4.19) boot.img fastboot flash boot patched.img
Android 7, 8, 9 (No boot ramdisk) Legacy Non-SAR recovery.img fastboot flash recovery patched.img
Modern Android 15/16 (Vendor Boot) Vendor Ramdisk Configurations vendor_boot.img fastboot flash vendor_boot patched.img
Home Docs CLI Reference

CLI Binaries & Tools Reference

Magisk bundles a suite of four primary native executables and symlinked applets located in the Magisk tmpfs path ($(magisk --path)) and /data/adb/magisk.

1. magisk (Daemon & Management Interface)

magisk CLI flags
$magisk -v # Print Magisk version string (e.g. 30.7) $magisk -V # Print numeric versionCode (e.g. 30700) $magisk --path # Print current base tmpfs folder (/debug_ramdisk) $magisk --install-module <zip> # Install a Magisk module zip package $magisk --remove-modules # Remove all modules and reboot device $magisk --denylist status # Query DenyList enforcement status $magisk --denylist enable # Enable DenyList process isolation $magisk --denylist add <pkg> # Add application package to DenyList $magisk --denylist rm <pkg> # Remove application from DenyList $magisk --sqlite <query> # Query the internal Magisk SQLite database

2. magiskboot (Boot Image Toolkit)

magiskboot performs all unpacking, patching, repacking, and header modifications natively:

magiskboot usage syntax
$magiskboot unpack [-n] [-h] <bootimg> # Unpacks kernel, ramdisk.cpio, dtb, and second components to current directory $magiskboot repack [-n] <origbootimg> [outbootimg] # Repacks components from current dir into new-boot.img matching original headers $magiskboot cpio <incpio> [commands...] # Supported CPIO actions: exists, rm, mkdir, ln, mv, add, extract, patch $magiskboot hexpatch <file> <hexpattern1> <hexpattern2> # Find and replace hex sequences in binary files $magiskboot extract <payload.bin> [partition] [outfile] # Extract partitions directly from OTA payload.bin

resetprop-ref">3. resetprop (System Property Modifier)

resetprop allows reading, creating, modifying, and deleting Android build properties (including read-only ro.* properties) directly in property memory without restarting services:

resetprop command examples
$resetprop -n ro.boot.flash.locked 1 # Modify property without notifying property_service $resetprop -d ro.debuggable # Delete a property $resetprop -f /data/local.prop # Load properties from file $resetprop -w sys.boot_completed 0 # Wait until property reaches target value

magiskpolicy-ref">4. magiskpolicy (Live SELinux Policy Engine)

Inject custom SELinux access vectors on live devices:

magiskpolicy statements
$magiskpolicy --live "allow { domain } { magisk } chr_file { ioctl read write }" $magiskpolicy --load sepolicy --save sepolicy.out "permissive my_daemon"

5. su (Superuser Management)

su command options
$su -c <command> # Pass command string to shell $su -mm # Mount master: inherit and run in the global mount namespace $su -v # Print su binary version string $su --drop-cap # Drop Linux capabilities when switching to non-root UID (v30.7+)
Home Docs Module Development

Magisk Module Specification

A Magisk module is an installable zip archive placed in /data/adb/modules/$MODID. Modules can replace system files, modify system properties, run boot scripts, and inject SELinux policies.

Module Directory Structure

Module Tree Layout
/data/adb/modules/$MODID/ ├── module.prop # Required: Metadata specification ├── system/ # Optional: Files to overlay onto /system │ ├── app/ # System applications │ ├── bin/ # Executables │ ├── etc/ # Config files (hosts, permissions, audio) │ ├── vendor/ # Symlinked to $MODID/system/vendor ├── zygisk/ # Optional: Native Zygisk binaries (arm64-v8a.so, etc.) ├── post-fs-data.sh # Optional: Runs before filesystem mounting completes ├── service.sh # Optional: Runs in late_start as background service ├── action.sh # Optional: Triggered when clicking Action in Magisk App ├── uninstall.sh # Optional: Runs before module removal ├── system.prop # Optional: Properties injected via resetprop ├── sepolicy.rule # Optional: Custom SELinux rule declarations ├── skip_mount # Flag: If present, system/ folder is not mounted ├── disable # Flag: If present, module is disabled └── remove # Flag: If present, module is deleted on next boot

module.prop Strict Schema

The module.prop file must strictly adhere to the following key-value format using UNIX (LF) line endings:

module.prop schema
id=my_custom_module name=My Custom Module version=v1.0.0 versionCode=100 author=DeveloperName description=A high-performance systemless customization module for Android. updateJson=https://raw.githubusercontent.com/user/repo/master/update.json

Lifecycle Scripts (*.sh)

Always determine your module's base directory dynamically using MODDIR=${0%/*}. Never hardcode absolute paths:

service.sh template
#!/system/bin/sh # Do NOT assume where your module will be located. # ALWAYS use $MODDIR to get your module's base folder MODDIR=${0%/*} # Wait for boot completion before running background tweaks resetprop -w sys.boot_completed 0 # Execute your custom optimization or service logic echo "Module started successfully" >> "$MODDIR/service.log"

BusyBox ASH Standalone Shell Mode

All Magisk scripts execute inside BusyBox's ash shell with Standalone Shell Mode enabled. In this mode, commands like ls, rm, and cp directly invoke BusyBox's internal applets rather than system binaries in /system/bin, guaranteeing uniform execution across all Android versions.

Home Docs Zygisk Native API

Zygisk Native Module API

Zygisk enables native C++ code injection inside the Zygote process. Modules export an implementation of the zygisk::ModuleAbi interface defined in zygisk.hpp.

Sample Zygisk Module (main.cpp)
#include <cstdlib> #include <unistd.h> #include <android/log.h> #include "zygisk.hpp" using zygisk::Api; using zygisk::AppSpecializeArgs; using zygisk::ServerSpecializeArgs; class MyZygiskModule : public zygisk::ModuleBase { public: void onLoad(Api *api, JNIEnv *env) override { this->api = api; this->env = env; } void preAppSpecialize(AppSpecializeArgs *args) override { // Runs in app process before UID and sandbox drop api->setOption(zygisk::Option::DLCLOSE_MODULE_LIBRARY); } void postAppSpecialize(const AppSpecializeArgs *args) override { // Runs in app process after sandbox is initialized } private: Api *api; JNIEnv *env; }; REGISTER_ZYGISK_MODULE(MyZygiskModule)

Companion IPC Sockets

If your Zygisk module requires root privileges, register a companion handler via REGISTER_ZYGISK_COMPANION(my_handler). Magisk will execute the handler inside a root daemon process and provide a direct UNIX socket connection back to the sandboxed application process.

Home Docs Troubleshooting

Troubleshooting & Bootloop Recovery

If a faulty module or incorrect SELinux rule prevents your device from booting into Android, use one of the standard recovery mechanisms below:

1. Emergency ADB Command

Connect your device via USB to a computer with ADB installed and run:

Purge All Modules via ADB
$adb wait-for-device shell magisk --remove-modules

2. Hardware Key Combo Safe Mode

Press and hold the Volume Down key right before the splash screen / boot animation appears. Magisk's early init detects the keypress and writes disable flags across all modules, allowing the device to boot to normal Android with modules disabled.

3. Complete Uninstallation

To restore your device to a 100% factory state, open the Magisk app and select Uninstall -> Complete Uninstall. Magisk will restore your stock boot partition and reboot. Alternatively, flash your factory stock boot.img or init_boot.img via Fastboot:

Restore Stock Boot Image
$fastboot flash init_boot stock_init_boot.img $fastboot reboot