Tools

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.

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.

ActionWhat it doesExit 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 certificate0 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 givenv31.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 inputDefault: init_boot, else boot
hexpatch <file> <from> <to>Find a hex pattern and replace itNon-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 | testPrint the device tree (-f: fstab nodes only), remove verity/AVB flags from fstab (honours KEEPVERITY), or test ittest: 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
cleanupDelete 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/stdoutv30.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

Unpack, edit, repack
$./magiskboot unpack -h boot.img # ...modify the extracted components... $./magiskboot repack boot.img new-boot.img $./magiskboot cleanup
  • Files unpack can create: kernel, kernel_dtb, ramdisk.cpio, second, dtb, extra, recovery_dtbo, and header with -h. A v4 vendor_boot image with several ramdisks gets a vendor_ramdisk/ folder with one .cpio per ramdisk (for example vendor_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, plus KERNEL_FMT and RAMDISK_FMT, and markers like VENDOR_BOOT_HDR, SAMSUNG_SEANDROID, AVB1_SIGNED or VBMETA. 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. Edit header before 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

  1. 1unpackExit 3 means vendor_boot
  2. 2cpio testStock, already Magisk, or unsupported
  3. 3Patch ramdiskAdd magiskinit as init, back up the original
  4. 4dtb patchOnly if verity is not kept
  5. 5Kernel hexpatchesSamsung RKP, defex, PROCA
  6. 6repacknew-boot.img
Condensed from scripts/boot_patch.sh at tag v31.1 (the same steps as v30.7 apart from the stub app and ChromeOS signing), checked 26 October 2026.
The core magiskboot calls in boot_patch.sh (v31.1, simplified)
$./magiskboot unpack boot.img $./magiskboot cpio ramdisk.cpio test # 0 = stock: keep a copy of the original ramdisk for the backup $cp ramdisk.cpio ramdisk.cpio.orig $./magiskboot compress=xz magisk magisk.xz $./magiskboot compress=xz init-ld init-ld.xz $./magiskboot cpio ramdisk.cpio "add 0750 init magiskinit" "mkdir 0750 overlay.d" "mkdir 0750 overlay.d/sbin" "add 0644 overlay.d/sbin/magisk.xz magisk.xz" "add 0644 overlay.d/sbin/init-ld.xz init-ld.xz" "patch" "backup ramdisk.cpio.orig" "mkdir 000 .backup" "add 000 .backup/.magisk config" $./magiskboot repack boot.img
  • The script looks for the ramdisk at ramdisk.cpio, then vendor_ramdisk/init_boot.cpio, then vendor_ramdisk/ramdisk.cpio. If cpio test returns 1 (already patched), it first restores the stock ramdisk from the backup, so re-patching a patched image works.
  • config is a small text file the script writes with KEEPVERITY, KEEPFORCEENCRYPT, RECOVERYMODE, VENDORBOOT, the pre-init device and the stock image's SHA-1. The binaries (magiskinit, magisk, init-ld) come from the APK's lib/<abi>/ folder.
  • For each of dtb, kernel_dtb and extra the script runs dtb test and dtb 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 with futility. 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.

magiskboot 31.1 on Google's GKI boot image android12-5.10-2026-07_r2
$sha256sum boot-5.10.img 8b03330b1690b365b88a6f7c0b746391eaca790cb5b96b77193000ad3b7c850e boot-5.10.img $./magiskboot unpack boot-5.10.img Parsing boot image: [boot-5.10.img] HEADER_VER [4] KERNEL_SZ [46929092] RAMDISK_SZ [1380091] OS_VERSION [12.0.0] OS_PATCH_LEVEL [2026-11] PAGESIZE [4096] CMDLINE [] KERNEL_FMT [raw] RAMDISK_FMT [lz4_legacy] VBMETA $./magiskboot cpio ramdisk.cpio test; echo "exit code $?" Loading cpio: [ramdisk.cpio] exit code 0 $./magiskboot cpio ramdisk.cpio ls Loading cpio: [ramdisk.cpio] drwxr-xr-x 0 0 0 B 0:0 debug_ramdisk drwxr-xr-x 0 0 0 B 0:0 dev drwxr-xr-x 0 0 0 B 0:0 first_stage_ramdisk -rwxr-x--- 0 0 2.52 MB 0:0 init drwxr-xr-x 0 0 0 B 0:0 metadata drwxr-xr-x 0 0 0 B 0:0 mnt drwxr-xr-x 0 0 0 B 0:0 proc drwxr-xr-x 0 0 0 B 0:0 second_stage_resources drwxr-xr-x 0 0 0 B 0:0 sys drwxr-xr-x 0 0 0 B 0:0 system

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:

Extract from payload.bin
# extracts init_boot, or boot if there is no init_boot $./magiskboot extract payload.bin # or name the partition and output file $./magiskboot extract payload.bin init_boot init_boot.img # stream it out of the OTA zip without unzipping to disk $unzip -p ota.zip payload.bin | ./magiskboot extract - boot boot.img

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.

CommandEffect
exists ENTRYExit 0 if ENTRY exists, else 1
ls [-r] [PATH]List PATH (/ by default); -r recursively
rm [-r] ENTRYRemove an entry; -r recursively
mkdir MODE ENTRYCreate a directory with permissions MODE
ln TARGET ENTRYCreate a symlink
mv SOURCE DESTMove or rename
add MODE ENTRY INFILEAdd a file (replaces ENTRY if it exists)
extract [ENTRY OUT]Extract one entry, or everything into the current directory
testExit 0 stock, 1 Magisk-patched, 2 unsupported (patched by something else)
patchApply Magisk's ramdisk patches (honours KEEPVERITY, KEEPFORCEENCRYPT)
backup ORIG [-n]Store a backup of the original ramdisk inside the archive; -n skips compression
restoreRestore the original ramdisk from that backup
Is this image already patched?
$./magiskboot unpack init_boot.img $./magiskboot cpio ramdisk.cpio test; echo $? $./magiskboot cpio ramdisk.cpio "ls -r /overlay.d"

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 to magiskboot and 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. Avoid magiskboot.exe files 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) replaces futility, and sign became sign-avb1; AVB 1.0 ECDSA signing and verification fixed; Samsung SignerVer02 signatures preserved; architecture-specific BCJ filters for XZ and better zImage detection; zopfli removed; 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.

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.

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