Android_boot_image_editor

> 编程语言

Open source

Parsing and re-packing Android boot.img/vbmeta.img/payload.bin, supporting Android 16

1.3K stars0 likes0 views

Website GitHub

About

Parsing and re-packing Android boot.img/vbmeta.img/payload.bin, supporting Android 16

Android_boot_image_editor

A tool for reverse engineering Android ROM images.

Requirements

Make sure you have JDK17+ and Python3.

Linux / WSL: sudo apt install git device-tree-compiler lz4 xz-utils zlib1g-dev openjdk-17-jdk gcc g++ python3 python-is-python3 p7zip-full android-sdk-libsparse-utils erofs-utils
Mac: brew install lz4 xz dtc
Windows: Install openssl and device-tree compiler with chocolate choco install openssl dtc-msys2 zip vim gzip 7zip

Getting Started

Put your boot.img to current directory, then start gradle 'unpack' task:

bash

cp  boot.img
./gradlew unpack

Your get the flattened kernel and /root filesystem under ./build/unzip_boot:

build/unzip_boot/
├── boot.json     (boot image info)
├── boot.avb.json (AVB only)
├── kernel
├── second        (2nd bootloader, if exists)
├── dtb           (dtb, if exists)
├── dtbo          (dtbo, if exists)
└── root          (extracted initramfs)

Then you can edit the actual file contents, like rootfs or kernel. Now, pack the boot.img again

./gradlew pack

You get the repacked boot.img at $(CURDIR):

boot.img.signed

Well done you did it! The last step is to star this repo :smile

live demo

Supported ROM image types

Image Type	file names	platforms	note
boot	boot.img, init_boot.img, boot-debug.img, boot-test-harness.img	all
vendor boot	vendor_boot.img, vendor_boot-debug.img, vendor_kernel_boot.img	all
recovery	recovery.img, recovery-two-step.img	all
vbmeta	vbmeta.img, vbmeta_system.img etc.	all
dtbo	dtbo.img	linux & mac
dtb	*.dtb	linux & mac
sparse images	system.img, vendor.img, product.img etc.	linux
OTA payload	payload.bin	all	Windows git-bash

Please note that the boot.img MUST follows AOSP verified boot flow, either Boot image signature in VBoot 1.0 or AVB HASH footer (a.k.a. AVB) in VBoot 2.0.

compatible devices

Device Model	Manufacturer	Compatible	Android Version	Note
Pixel 7 (panther)	Google	Y	13 (TQ2A.230505.002)
2023)
ADT-3 (adt3)	Askey/Google	Y	12 (spp2.210219.010)	amlogic inside,
Android TV
Pixel 3 (blueline)	Google	Y	12 (spp2.210219.008,
2021)
Pixel 3 (blueline)	Google	Y	11 (RP1A.200720.009,
2020)	more ...
Pixel 3 (blueline)	Google	Y	Q preview (qpp2.190228.023,
2019)	more ...
Redmi K30 4G (phoenix[n])	XiaoMi	Y	10	verified by @eebssk1
TS10	Topway	Y	10	car headunit, @mariodantas
Pixel XL (marlin)	HTC	Y	9.0.0 (PPR2.180905.006,
Sep 2018)	more ...
K3 (CPH1955)	OPPO	Y for recovery.img
N for boot.img	Pie	more
Z18 (NX606J)	ZTE	Y	8.1.0	more...
Nexus 9 (volantis/flounder)	HTC	Y(with some tricks)	7.1.1 (N9F27M, Oct 2017)	tricks
Nexus 5x (bullhead)	LG	Y	6.0.0_r12 (MDA89E)
Moto X (2013) T-Mobile	Motorola	N
X7 (PD1602_A_3.12.8)	VIVO	N	?	Issue 35
Realme GT Neo 3	Realme	N	12	Issue 105

more examples

working with recovery.img

Please remember to clean the work directory first.

bash

rm *.img
cp  recovery.img
./gradlew unpack
./gradlew pack

working with vbmeta.img

bash

rm *.img
cp  vbmeta.img
./gradlew unpack
./gradlew pack

clean workspace When you finished current work and need to clean the workspace for next image, it's a good idea to call the clear command:

bash

./gradlew clear

working with boot.img and vbmeta.img

If your vbmeta.img contains hash of boot.img, you MUST update vbmeta image together.

bash

rm *.img
cp  boot.img
cp  vbmeta.img
./gradlew unpack
./gradlew pack

Your boot.img.signed and vbmeta.img.signd will be updated together, then you can flash them to your device.

working with vendor_boot.img + vbmeta.img (Pixel 5 etc.) Most devices include hash descriptor of vendor_boot.img in vbmeta.img, so if you need to modify vendor_boot.img, you need to update vbmeta.img together.

bash

rm *.img
cp  vendor_boot.img
cp  vbmeta.img
./gradlew unpack
./gradlew pack
./gradlew flash

Please note that to use 'gradle flash', your host machine must be connectted to your DUT with adb, and you already 'adb root'.

How to edit device tree blob(dtb) inside vendor_boot.img

If you want to edit the device-tree blob in place:

bash

cp  vendor_boot.img
cp  vbmeta.img
./gradlew unpack
==> now you can edit build/unzip_boot/dtb.dts directly
./gradlew pack

During unpack stage, dtb will be dumped to file build/unzip_boot/dtb, dts will be decompiled to build/unzip_boot/dtb.dts. You can edit dtb.dts directly, and it will be compiled to dtb duing repack stage.

If you just want to replace the dtb with the one that is compiled outside this tool, please

bash

cp  vendor_boot.img
cp  vbmeta.img
./gradlew unpack
rm build/unzip_boot/dtb.dts
cp  build/unzip_boot/dtb
./gradlew pack

How to pull device tree blob(dtb) from a rooted device

If you have a rooted device and want to pull /proc/device-tree

bash

touch fake.dtb
./gradlew pull

This tool will copy dtc to the target device via adb, and dump the dtb and dts file. Eventually you should get something like this

+--------+------------------------------+
|  What  |            Where             |
+--------+------------------------------+
| source | /proc/device-tree            |
+--------+------------------------------+
| DTB    | panther.dtb                  |
+--------+------------------------------+
| DTS    | build/unzip_boot/panther.dts |
+--------+------------------------------+

How to work edit device tree blob(dtb) file

If you have a dtb file and want to edit its content

bash

cp  .
./gradlew unpack

This tool will decompile it and put the decompiled source to build/unzip_boot.

                        Unpack Summary of panther.dtb
+------+------------------------------+
| What |            Where             |
+------+------------------------------+
| DTB  | panther.dtb                  |
+------+------------------------------+
| DTS  | build/unzip_boot/panther.dts |
+------+------------------------------+

working with system.img

bash

cp  system.img
./gradlew unpack

You get system.img.unsparse, that's a plain ext4 filesystem data.

How to disable AVB verification

The idea is to set flag=2 in main vbmeta.

bash

rm *.img
cp  vbmeta.img
./gradlew unpack
vim -u NONE -N build/unzip_boot/vbmeta.avb.json  -c ":19s/0/2/g" -c ":wq"
./gradlew pack

Then flash vbmeta.img.signed to your device.

How to merge init_boot.img into boot.img

unpack init_boot.img and copy out "build/unzip_boot/root".
clear workspace by gradle clear, then unpack boot.img
copy back the "build/unzip_boot/root"
edit build/unzip_boot/boot.json

change ramdisk.size to 1
change ramdisk.file from "build/unzip_boot/ramdisk.img" to "build/unzip_boot/ramdisk.img.lz4"

work with payload.bin
extract everything

Usage:

    gradle unpack

extract only 1 specified partition Usage:

    gradle unpack -Dpart=

Example:

    gradle unpack -Dpart=boot
    gradle unpack -Dpart=system

Note: "build/payload/" will be deleted before each "unpack" task

work with apex images

AOSP already has tools like apexer, deapexer, sign_apex.py, these should suffice the needs on .apex and .capex. Refer to Issue https://github.com/cfig/Android_boot_image_editor/issues/120

For those who may be interested in apex generation flow, there is a graph here

How to work with vendor_dlkm.img

bash

cp  vendor_dlkm.img
cp  vbmeta.img
./gradlew unpack
# replace your .ko
./gradlew pack

Then flash vbmeta.img.signed and vendor_dlkm.img.signed to the device.

boot.img layout

Read boot layout of Android boot.img and vendor_boot.img. Read misc layout of misc.img

References and Acknowledgement

more ...

Android version list https://source.android.com/source/build-numbers.html

Android build-numbers https://source.android.com/setup/start/build-numbers

cpio & fs_config

https://android.googlesource.com/platform/system/core

https://www.kernel.org/doc/Documentation/early-userspace/buffer-format.txt

AVB

https://android.googlesource.com/platform/external/avb/

boot_signer

https://android.googlesource.com/platform/system/extras

mkbootimg

https://android.googlesource.com/platform/system/tools/mkbootimg/+/refs/heads/master/

boot header definition

https://android.googlesource.com/platform/system/tools/mkbootimg/+/refs/heads/master/include/bootimg/bootimg.h

kernel info extractor

https://android.googlesource.com/platform/build/+/refs/heads/master/tools/extract_kernel.py

mkdtboimg

https://android.googlesource.com/platform/system/libufdt/

libsparse

https://android.googlesource.com/platform/system/core/+/refs/heads/master/libsparse/

Android Nexus/Pixle factory images

https://developers.google.cn/android/images

Issues· 0 open

View all issues Open on GitHub

No open issues yet, or sync has not completed.

> Tags

Javaandroid-bootavbmkbootmkbootimg

No comments yet. Be the first to share.

> Details

PublishedAug 1, 2026

UpdatedSep 17, 2026

Category编程语言

PricingOpen source

> Related tools

TypeScript

JavaScript 的超集，为前端与全栈提供静态类型

Python

通用编程语言，广泛用于 Web、数据与 AI

Google 推出的简洁高效系统语言

Android_boot_image_editor

About

Android_boot_image_editor

Requirements

Getting Started

live demo

Supported ROM image types

compatible devices

more examples

boot.img layout

References and Acknowledgement

Issues· 0 open

> Tags

> Discussion

> Details

> Related tools