Developer Guides


Magisk ships with a feature complete BusyBox binary (including full SELinux support). The executable is located at /data/adb/magisk/busybox. Magisk’s BusyBox supports runtime toggle-able “ASH Standalone Shell Mode”. What this standalone mode means is that when running in the ash shell of BusyBox, every single command will directly use the applet within BusyBox, regardless of what is set as PATH. For example, commands like ls, rm, chmod will NOT use what is in PATH (in the case of Android by default it will be /system/bin/ls, /system/bin/rm, and /system/bin/chmod respectively), but will instead directly call internal BusyBox applets. This makes sure that scripts always run in a predictable environment and always have the full suite of commands no matter which Android version it is running on. To force a command not to use BusyBox, you have to call the executable with full paths.

Every single shell script running in the context of Magisk will be executed in BusyBox’s ash shell with standalone mode enabled. For what is relevant to 3rd party developers, this includes all boot scripts and module installation scripts.

For those who want to use this “Standalone Mode” feature outside of Magisk, there are 2 ways to enable it:

  1. Set environment variable ASH_STANDALONE to 1
    Example: ASH_STANDALONE=1 /data/adb/magisk/busybox sh <script>
  2. Toggle with command-line options:
    /data/adb/magisk/busybox sh -o standalone <script>

To make sure all subsequent sh shell executed also runs in standalone mode, option 1 is the preferred method (and this is what Magisk and the Magisk app internally use) as environment variables are inherited down to child processes.

Magisk Modules

A Magisk module is a folder placed in /data/adb/modules with the structure below:

├── .
├── .
├── $MODID                  <--- The folder is named with the ID of the module
│   │
│   │      *** Module Identity ***
│   │
│   ├── module.prop         <--- This file stores the metadata of the module
│   │
│   │      *** Main Contents ***
│   │
│   ├── system              <--- This folder will be mounted if skip_mount does not exist
│   │   ├── ...
│   │   ├── ...
│   │   └── ...
│   │
│   │      *** Status Flags ***
│   │
│   ├── skip_mount          <--- If exists, Magisk will NOT mount your system folder
│   ├── disable             <--- If exists, the module will be disabled
│   ├── remove              <--- If exists, the module will be removed next reboot
│   │
│   │      *** Optional Files ***
│   │
│   ├──     <--- This script will be executed in post-fs-data
│   ├──          <--- This script will be executed in late_start service
|   ├──        <--- This script will be executed when Magisk removes your module
│   ├── system.prop         <--- Properties in this file will be loaded as system properties by resetprop
│   ├── sepolicy.rule       <--- Additional custom sepolicy rules
│   │
│   │      *** Auto Generated, DO NOT MANUALLY CREATE OR MODIFY ***
│   │
│   ├── vendor              <--- A symlink to $MODID/system/vendor
│   ├── product             <--- A symlink to $MODID/system/product
│   ├── system_ext          <--- A symlink to $MODID/system/system_ext
│   │
│   │      *** Any additional files / folders are allowed ***
│   │
│   ├── ...
│   └── ...
├── another_module
│   ├── .
│   └── .
├── .
├── .


This is the strict format of module.prop


Shell scripts (*.sh)

Please read the Boot Scripts section to understand the difference between and For most module developers, should be good enough if you just need to run a boot script.

In all scripts of your module, please use MODDIR=${0%/*} to get your module’s base directory path; do NOT hardcode your module path in scripts.


This file follows the same format as build.prop. Each line comprises of [key]=[value].


If your module requires some additional sepolicy patches, please add those rules into this file. The module installer script and Magisk’s daemon will make sure this file is copied to somewhere magiskinit can read pre-init to ensure these rules are injected properly.

Each line in this file will be treated as a policy statement. For more details about how a policy statement is formatted, please check magiskpolicy’s documentation.

The system folder

All files you want Magisk to replace/inject for you should be placed in this folder. Please read through the Magic Mount section to understand how Magisk mount your files.

Magisk Module Installer

A Magisk Module Installer is a Magisk Module packaged in a zip file that can be flashed in the Magisk app or custom recoveries such as TWRP. An installer has the same file structure as a Magisk module (please check the previous section for more info). The simplest Magisk Module Installer is just a Magisk Module packed in a zip file, with addition to the following files:

By default, update-binary will check/setup the environment, load utility functions, extract the module installer zip to where your module will be installed, and finally do some trivial tasks and cleanups, which should cover most simple modules’ needs.
│   └── com
│       └── google
│           └── android
│               ├── update-binary      <--- The you downloaded
│               └── updater-script     <--- Should only contain the string "#MAGISK"
├──                       <--- (Optional, more details later)
│                                           This script will be sourced by update-binary
├── ...
├── ...  /* The rest of module's files */


If you need to customize the module installation process, optionally you can create a new script in the installer called This script will be sourced (not executed!) by update-binary after all files are extracted and default permissions and secontext are applied. This is very useful if your module includes different files based on ABI, or you need to set special permissions/secontext for some of your files (e.g. files in /system/bin).

If you need even more customization and prefer to do everything on your own, declare SKIPUNZIP=1 in to skip the extraction and applying default permissions/secontext steps. Be aware that by doing so, your will then be responsible to install everything by itself. Environment

This script will run in Magisk’s BusyBox ash shell with “Standalone Mode” enabled. The following variables and shell functions are available for convenience:

ui_print <msg>
    print <msg> to console
    Avoid using 'echo' as it will not display in custom recovery's console

abort <msg>
    print error message <msg> to console and terminate the installation
    Avoid using 'exit' as it will skip the termination cleanup steps

set_perm <target> <owner> <group> <permission> [context]
    if [context] is not set, the default is "u:object_r:system_file:s0"
    this function is a shorthand for the following commands:
       chown target
       chmod permission target
       chcon context target

set_perm_recursive <directory> <owner> <group> <dirpermission> <filepermission> [context]
    if [context] is not set, the default is "u:object_r:system_file:s0"
    for all files in <directory>, it will call:
       set_perm file owner group filepermission context
    for all directories in <directory> (including itself), it will call:
       set_perm dir owner group dirpermission context
Easy Replace

You can declare a list of folders you want to directly replace in the variable name REPLACE. The module installer script will pickup this variable and create .replace files for you. An example declaration:


The list above will result in the following files being created: $MODPATH/system/app/YouTube/.replace and $MODPATH/system/app/Bloatware/.replace


Submit Modules

You can submit a module to Magisk-Module-Repo so users can download your module directly in the Magisk app.

Module Tricks

Remove Files

How to remove a file systemless-ly? To actually make the file disappear is complicated (possible, not worth the effort). Replacing it with a dummy file should be good enough! Create an empty file with the same name and place it in the same path within a module, it shall replace your target file with a dummy file.

Remove Folders

Same as mentioned above, actually making the folder disappear is not worth the effort. Replacing it with an empty folder should be good enough! A handy trick for module developers is to add the folder you want to remove into the REPLACE list within If your module doesn’t provide a corresponding folder, it will create an empty folder, and automatically add .replace into the empty folder so the dummy folder will properly replace the one in /system.

Boot Scripts

In Magisk, you can run boot scripts in 2 different modes: post-fs-data and late_start service mode.

In Magisk, there are also 2 kinds of scripts: general scripts and module scripts.

These scripts will run in Magisk’s BusyBox ash shell with “Standalone Mode” enabled.

Root Directory Overlay System

Since / is read-only on system-as-root devices, Magisk provides an overlay system to enable developers to replace files in rootdir or add new *.rc scripts. This feature is designed mostly for custom kernel developers.

Overlay files shall be placed in the overlay.d folder in boot image ramdisk, and they follow these rules:

  1. All *.rc files in overlay.d will be read and concatenated AFTER init.rc
  2. Existing files can be replaced by files located at the same relative path
  3. Files that correspond to a non-existing file will be ignored

In order to have additional files that you want to reference in your custom *.rc scripts, add them in overlay.d/sbin. The 3 rules above does not apply to everything in this specific folder, as they will directly be copied to Magisk’s internal tmpfs directory (which used to always be located at /sbin).

Due to changes in Android 11, the /sbin folder is no longer guaranteed to exist. In that case, Magisk randomly generates the tmpfs folder. Every occurrence of the pattern ${MAGISKTMP} in your *.rc scripts will be replaced with the Magisk tmpfs folder when magiskinit injects it into init.rc. This also works on pre Android 11 devices as ${MAGISKTMP} will simply be replaced with /sbin in this case, so the best practice is to NEVER hardcode /sbin in your *.rc scripts when referencing additional files.

Here is an example of how to setup overlay.d with custom *.rc script:

├── overlay.d
│   ├── sbin
│   │   ├── libfoo.ko      <--- These 2 files will be copied
│   │   └──    <--- to Magisk's tmpfs directory
│   ├── custom.rc          <--- This file will be injected into init.rc
│   ├── res
│   │   └── random.png     <--- This file will replace /res/random.png
│   └── new_file           <--- This file will be ignored because
│                               /new_file does not exist
├── res
│   └── random.png         <--- This file will be replaced by
│                               /overlay.d/res/random.png
├── ...
├── ...  /* The rest of initramfs files */

Here is an example of the custom.rc:

# Use ${MAGISKTMP} to refer to Magisk's tmpfs directory

on early-init
    setprop bar
    insmod ${MAGISKTMP}/libfoo.ko
    start myservice

service myservice ${MAGISKTMP}/