magiskboot: commands and where to get it
magiskboot is the tool Magisk uses to take boot images apart and put them back together. The Magisk app runs it for you when it patches an image; you can also run it yourself to inspect an image, patch one by hand, edit a ramdisk or pull a boot image out of an OTA payload.
Last updated 8 sourcesHow we check pages
What it supports
Unpacking and repacking Android boot, init_boot, vendor_boot and recovery images (including several vendor wrappers such as Samsung SEAndroid, MTK headers and LG bump), CPIO (ramdisk) editing, device tree (DTB) patching, hex patching, AVB 1.0 and ChromeOS signing, and compression in gzip, xz, lzma, bzip2, lz4, lz4_legacy and lz4_lg (the LG variant), all without external tools.
- Separate download?NoInside the Magisk APK and on rooted phones
- Official platformsAndroidx86_64 build is a static Linux ELF; v31.1 can be built for Linux and macOS
- Windows .exeNo official buildOnly an archived community port
- Needed to root?NoThe Magisk app runs it for you
All commands
Usage: magiskboot <action> [args...]. Run it with no arguments to print the full help of the version you have. Differences between the current v31.1 and the previous v30.7 are noted.
| Action | What it does | Exit codes and notes |
|---|---|---|
unpack [-n] [-h] <img> | Split the image into component files in the current directory, decompressing them. -n: leave them compressed. -h: also write the header to header. | 0 valid, 1 error, 3 vendor_boot. v30.7 also returns 2 for ChromeOS. |
repack [-n] <orig> [out] | Build a new image from the files in the current directory, using orig for headers and missing parts. Output defaults to new-boot.img. | v31.1 re-signs ChromeOS images automatically and keeps Samsung SignerVer02 signatures. |
verify <img> [x509.pem] | Check for an AVB 1.0 signature, optionally against a certificate | 0 valid, 1 error |
sign <img> [name] [x509.pem pk8] | Sign with AVB 1.0; without a key pair, the AOSP verity key built into magiskboot is used. Name defaults to /boot. | v30.7 only. Renamed sign-avb1 in v31.1. |
sign-chromeos <img> [out] | Sign with the ChromeOS developer keys built into magiskboot; overwrites the input if no output is given | v31.1 only (v30.7 used an external futility tool) |
extract <payload.bin> [partition] [out] | Extract one partition image from an OTA payload; - reads from standard input | Default: init_boot, else boot |
hexpatch <file> <from> <to> | Find a hex pattern and replace it | Non-zero if the pattern is not found |
cpio <incpio> [commands...] | Edit a ramdisk archive in place (table below) | Each command is one quoted argument |
dtb <file> print [-f] | patch | test | Print the device tree (-f: fstab nodes only), remove verity/AVB flags from fstab (honours KEEPVERITY), or test it | test: 0 valid, 1 error |
split [-n] <file> | Split an Image.*-dtb into kernel and kernel_dtb; -n leaves the kernel compressed | |
sha1 <file> | Print the SHA-1 checksum | |
cleanup | Delete the unpacked component files from the current directory | |
compress[=format] <in> [out] | Compress (gzip by default); without out, replaces the input with a suffixed file; - for stdin/stdout | v30.7 also accepts zopfli |
decompress <in> [out] | Detect the format and decompress |
Environment variables read by magiskboot itself: KEEPVERITY and KEEPFORCEENCRYPT (for cpio patch and dtb patch), and PATCHVBMETAFLAG=true (for repack, sets all disable flags in the image's vbmeta header). The patch script also uses RECOVERYMODE and LEGACYSAR, but those are not magiskboot options.
Unpack and repack
- Files unpack can create:
kernel,kernel_dtb,ramdisk.cpio,second,dtb,extra,recovery_dtbo, andheaderwith-h. A v4vendor_bootimage with several ramdisks gets avendor_ramdisk/folder with one.cpioper ramdisk (for examplevendor_ramdisk/init_boot.cpio). - What unpack prints (to stderr): the header fields, such as
HEADER_VER,KERNEL_SZ,RAMDISK_SZ,OS_VERSION,OS_PATCH_LEVEL,PAGESIZE,CMDLINE, plusKERNEL_FMTandRAMDISK_FMT, and markers likeVENDOR_BOOT_HDR,SAMSUNG_SEANDROID,AVB1_SIGNEDorVBMETA. It is a quick way to see what an image contains. - Repack reuses the original's headers and only updates sizes and checksums. Each component is recompressed in its original format unless the file in the directory is already compressed, or you pass
-n. Editheaderbefore repacking to change header values such as the command line. - Work in a clean directory. Any component file present is used, and anything missing is taken from the original image, so leftovers from another image produce a broken result.
Patching by hand, the way the app does it
The Magisk app's patch step is a shell script, boot_patch.sh, that drives magiskboot. Knowing the steps helps when you need to see where patching fails. For normal installs, let the app do it: patching a boot image.
What the Magisk app does when it patches an image
- 1unpackExit 3 means
vendor_boot - 2cpio testStock, already Magisk, or unsupported
- 3Patch ramdiskAdd
magiskinitasinit, back up the original - 4dtb patchOnly if verity is not kept
- 5Kernel hexpatchesSamsung RKP, defex, PROCA
- 6repack
new-boot.img
- The script looks for the ramdisk at
ramdisk.cpio, thenvendor_ramdisk/init_boot.cpio, thenvendor_ramdisk/ramdisk.cpio. Ifcpio testreturns 1 (already patched), it first restores the stock ramdisk from the backup, so re-patching a patched image works. configis a small text file the script writes withKEEPVERITY,KEEPFORCEENCRYPT,RECOVERYMODE,VENDORBOOT, the pre-init device and the stock image's SHA-1. The binaries (magiskinit,magisk,init-ld) come from the APK'slib/<abi>/folder.- For each of
dtb,kernel_dtbandextrathe script runsdtb testanddtb patch. On the kernel it tries three hexpatches that remove Samsung RKP and defex and disable Samsung PROCA; if none match, the original kernel is reused. - v30.7 additionally embedded the stub app (
overlay.d/sbin/stub.xz) used for app hiding, and signed ChromeOS images withfutility. Both are gone in v31.1.
Real output: unpacking Google's boot image
This is magiskboot from the v31.1 source, built for Linux, run by us on Google's official generic boot image for Android 12 kernels (android12-5.10-2026-07_r2). It shows what unpack reports for a header version 4 image and what a stock ramdisk contains. cpio test returning 0 means stock; on a Magisk-patched image it returns 1.
Lines 7 to 35 of the unedited output. Full log · how it was made
The same session continues with the full boot_patch.sh run and the patched image's contents: what patching actually changes.
Extract a boot image from payload.bin
Many phones (OnePlus, Nothing, Pixel OTAs and others) ship updates as a zip containing payload.bin. magiskboot can extract a partition directly:
With no partition given, check which of init_boot.img or boot.img was created to see which one it found. Incremental OTAs contain only differences and fail with delta payloads are not supported, please use a full payload file; you need a full OTA. Since v31.0 the app can also extract the image from an OTA URL itself. Brand-specific steps are in the OnePlus guide.
Working with the ramdisk (cpio)
magiskboot cpio <incpio> [commands...] edits a cpio archive in place. Each command is one quoted argument; several can be chained in one call.
| Command | Effect |
|---|---|
exists ENTRY | Exit 0 if ENTRY exists, else 1 |
ls [-r] [PATH] | List PATH (/ by default); -r recursively |
rm [-r] ENTRY | Remove an entry; -r recursively |
mkdir MODE ENTRY | Create a directory with permissions MODE |
ln TARGET ENTRY | Create a symlink |
mv SOURCE DEST | Move or rename |
add MODE ENTRY INFILE | Add a file (replaces ENTRY if it exists) |
extract [ENTRY OUT] | Extract one entry, or everything into the current directory |
test | Exit 0 stock, 1 Magisk-patched, 2 unsupported (patched by something else) |
patch | Apply Magisk's ramdisk patches (honours KEEPVERITY, KEEPFORCEENCRYPT) |
backup ORIG [-n] | Store a backup of the original ramdisk inside the archive; -n skips compression |
restore | Restore the original ramdisk from that backup |
Kernel developers use the same tool to add files to Magisk's overlay.d folder, which magiskinit applies at boot; see how Magisk works.
Where to get magiskboot (Android, Linux, macOS, Windows)
Magisk does not publish magiskboot as a separate download. Its GitHub releases contain only the Magisk APK, the debug APK and the source code. Your options:
- On a rooted phone: Magisk keeps its own copy at
/data/adb/magisk/magiskboot; its install scripts call it from there. - From the APK: the APK is a zip. It contains magiskboot for each architecture as
lib/<abi>/libmagiskboot.so(arm64-v8a, armeabi-v7a, x86 and x86_64), a statically linked executable; rename it tomagiskbootand make it executable. The x86_64 build is a Linux ELF file. Since v28.0 the static tools are built against a minimal libc. - Built yourself on Linux or macOS: v31.1 added support for building magiskboot natively on Linux and macOS hosts from Magisk's source. No prebuilt desktop binaries are published, and Magisk's build documentation does not give separate steps for it.
- Windows (
magiskboot.exe): there is no official build. The best-known community port, magiskboot_build, targeted Windows, macOS and other desktops, but it was archived on 16 August 2026 and is based on a Magisk v27.0 canary, so it may not handle newer image formats. WSL with the Linux binary is an alternative. Avoidmagiskboot.exefiles from download sites.
Recent changes
- v30.7: better LZMA detection and command-line parsing fixes.
- v31.0: zImage kernels no longer need exact size padding on repack; lower default XZ and LZMA presets to save memory; the AVB hash descriptor size was updated on repack (reverted in v31.1).
- v31.1 (current stable): native ChromeOS signing (
sign-chromeos, automatic re-signing on repack) replacesfutility, andsignbecamesign-avb1; AVB 1.0 ECDSA signing and verification fixed; SamsungSignerVer02signatures preserved; architecture-specific BCJ filters for XZ and better zImage detection;zopfliremoved; host builds for Linux and macOS.
Errors and questions
Invalid boot image header!, or unpack exits with code 1 and prints only the file name
The file is not a boot-type image magiskboot recognizes. Common causes: you passed vbmeta.img, super.img, a sparse image, a whole OTA zip or a Samsung .tar.md5 instead of the boot, init_boot, vendor_boot or recovery image. Extract the right image first (see the patching guide), or use extract on a payload.bin. Corrupted boot image! means the header was found but the sections run past the end of the file, usually a truncated download.
Unpack shows RAMDISK_SZ [0] and creates no ramdisk file
This boot image has no ramdisk. On most phones that launched with Android 13 or later the ramdisk is in init_boot.img, so patch that instead. If there is no init_boot either, the ramdisk is usually in vendor_boot, as on the Pixel 6 and several Redmi Note models we checked: Magisk patches this boot.img anyway and adds a ramdisk of its own (boot_patch.sh: "No ramdisk found, create one from scratch"), and v30.3 or later can patch vendor_boot.img instead. Only phones where the Magisk app shows Ramdisk: No need the recovery method.
Boot image patched by unsupported programs
cpio test returned 2: the ramdisk was modified by another root tool (or an old one) whose changes Magisk can't undo. Start again from the stock image of the exact firmware build that is installed.
Boot image dtb was patched by old (unsupported) Magisk
The device tree in the image still has changes from a very old Magisk. As the message says, patch an unpatched stock image.
The repacked image doesn't boot
Repack uses every component file in the current directory and takes anything missing from the original image. Leftover files from an earlier unpack (a stale kernel, dtb or header) end up in the new image. Run magiskboot cleanup or work in an empty directory for each image, and repack against the same original you unpacked.
Unsupported or unknown compression format
The format after compress= is not one magiskboot knows. Use one of gzip, xz, lzma, bzip2, lz4, lz4_legacy or lz4_lg. zopfli (a slower gzip-compatible encoder) is accepted by v30.7 but was removed in v31.1.
sign no longer works
In v31.1 the command was split into sign-avb1 (the same AVB 1.0 signing as v30.7's sign) and sign-chromeos.
Does magiskboot work on Samsung images?
Yes, the app patches the whole AP file and magiskboot handles the boot or init_boot image inside it. v31.1 keeps Samsung SignerVer02 signatures when repacking. The Samsung guide covers the full process, including why One UI 8 is a problem.
Where can I download magiskboot.exe?
There is no official Windows build. The community port magiskboot_build was archived on 16 August 2026 and is based on a Magisk v27.0 canary, so it may not handle newer images. Prefer the Magisk app, or run the Linux x86_64 binary under WSL. Avoid magiskboot.exe files from download sites.
No match. Try another word from the error message.
Do I need magiskboot to root? No. The Magisk app runs it when you choose Patch firmware / image (called Select and patch a file in v30.7 and older). Use magiskboot directly for inspection, scripting or custom kernel work. For SELinux changes in a patched image, see magiskpolicy; for root shell use, su.
Sources
This page is written from the sources below. If anything here disagrees with them, the upstream source is correct.
- Magisk tools reference: magiskboot (topjohnwu)
- Magisk changelog: magiskboot changes in v30.7, v31.0 and v31.1 (topjohnwu)
- Magisk source: magiskboot usage text, native/src/boot/cli.rs at v30.7 (topjohnwu)
- Magisk source: magiskboot usage text at v31.1 (topjohnwu)
- Magisk source: the app's patch script, scripts/boot_patch.sh at v31.1 (topjohnwu)
- Magisk releases: official downloads (topjohnwu)
- magiskboot_build, archived community desktop port (ookiineko)
- GKI android12-5.10 release builds (Android Open Source Project)
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