avbroot: repatching Android A/B OTAs so updates keep your root

What the tool actually does to an OTA

avbroot is a tool for modifying Android A/B OTA images reproducibly and re-signing them with custom keys, and it also includes a collection of subcommands for packing and unpacking numerous Android image formats. The project is written in Rust, licensed GPL-3.0, and the current version is 3.37.0 with the last push to the master branch on 2026-10-19, released the same day.

The mechanism is stated in the Patches section, and there are three patches applied to the partition images.

The boot or init_boot image, depending on the device, is patched to enable root access if requested.

The boot, recovery or vendor_boot image, also depending on the device, is patched to replace the OTA signature verification certificates with the custom OTA signing certificate. The reason given is twofold: it allows future patched OTAs to be sideloaded from recovery mode after the bootloader has been locked, and it prevents accidental flashing of the original unpatched OTA.

The system image is also patched to replace the OTA signature verification certificates, which prevents the OS system updater app from installing an unpatched OTA and also allows the use of custom OTA updater apps.

That last point is the one that makes the tool exist. Without it, a rooted device that receives a system update either loses root or ends up with a mismatched boot state, and the standard answer of not updating is not a long term answer. Patching the system image is what allows the official updater to run and still end up with a rooted, correctly signed system.

The README opens by recommending a good understanding of how AVB and A/B OTAs work before using the tool, and asks that the warnings and caveats be well understood to avoid the risk of hard bricking.

The device requirements, and how to check them

Two requirements decide whether the tool is usable on your device, and the first is checkable from the OTA file itself.

Only devices that use modern A/B partitioning are supported, and the README says this is the case for most non-Samsung devices launched with Android 10 or newer. To check whether a device uses this partitioning scheme, you open the OTA zip file and check that payload.bin exists, and that META-INF/com/android/metadata exists for Android 10 and 11, or META-INF/com/android/metadata.pb for Android 12 and later. Those two file checks are the whole diagnostic, and they are worth doing before anything else because the tool's failure modes assume the scheme is present.

The second requirement is that the device must support using a custom public key for the bootloader's root of trust, which is normally done via the fastboot flash avb_custom_key command. A list of devices known to work is in the issue tracker, at issue 299.

The Samsung exclusion belongs to the partitioning requirement: most non-Samsung devices launched with Android 10 or newer use this scheme.

One more detail appears in the key generation section and is worth knowing. The Pixel 11 series supports post-quantum ML-DSA keys for AVB, but those devices ship from the factory with old GSC firmware that breaks registering ML-DSA keys with the bootloader. The device must be upgraded to the latest stock OS first and must boot the new OS version once for the GSC firmware to update. So the key algorithm you can use depends on the firmware the device happens to be running.

Two keys, and why per-device keys matter

avbroot signs several components while patching an OTA zip, and the list tells you how much of the chain has to agree.

It signs the boot images, the vbmeta images, the OTA payload and the OTA zip itself. The first two components are signed with an AVB key and the latter two with an OTA key. They can be the same key, though the documented steps generate two separate ones.

The key generation for the Pixel 11 series uses the post-quantum algorithm for the AVB key:

avbroot key generate-key -t mldsa65 -o avb.key
avbroot key generate-key -t rsa4096 -o ota.key

The recommendation about per-device keys is the one to take seriously. When patching OTAs for multiple devices, generating unique keys for each device is strongly recommended because it prevents an OTA for the wrong device being accidentally flashed.

That is a small addition to the process with a large payoff. The failure it prevents is not a wrong flash of an obviously wrong image, it is flashing a valid, correctly signed OTA built for a different phone onto this one, where the symptom is a boot loop with no clear cause. Key separation turns that from a mystery into an immediate rejection.

The same rule appears later in the usage section, where it says that if you are updating Android, Magisk or KernelSU after you have already done an initial setup, there is no need to generate new signing keys, because any further updates must use the keys that were created during the initial setup. The keys are therefore part of the device's identity from the first patch onwards, and losing them means losing the ability to update.

Patching the OTA, and the four ways to configure root

The base command is the same regardless of which root implementation you want, with the key paths given and the input zip named:

avbroot ota patch \
    --input /path/to/ota.zip \
    --key-avb /path/to/avb.key \
    --key-ota /path/to/ota.key \
    --cert-ota /path/to/ota.crt \

What varies is the extra arguments, and there are four cases. To enable root with Magisk, you pass the Magisk apk and the preinit partition name:

--magisk /path/to/magisk.apk
--magisk-preinit-device <name>

If you do not know the Magisk preinit partition name, the README points at a section with the steps to find it.

If you would rather patch the boot image through the Magisk app yourself, you pass the already patched image instead:

--prepatched /path/to/magisk_patched-xxxxx_yyyyy.img

For KernelSU, the same argument carries the KernelSU boot image:

--prepatched /path/to/kernelsu/boot.img

And to leave the operating system unrooted, which is what you want when you are removing root while keeping the device updatable:

--rootless

If --output is not specified, the output file is written to <input>.patched. The tool is a standalone executable, so it does not need to be installed and can be run from anywhere, and the workflow after patching splits into an initial setup for the first flash and an updates path for everything after, which is a distinction that matters because the first flash and a subsequent update have different prerequisites around the bootloader lock state.

The warnings, and the one rule that decides whether you brick

The warnings and caveats section is the most important part of the README, and it is worth reading in full before anything else.

The first warning is the one that decides everything. Always leave the OEM unlocking checkbox enabled when using a locked bootloader while rooted. The README says this is critically important. Root access allows the boot partition to potentially be overwritten, either accidentally or intentionally, with an image that is not properly signed. In that scenario, if the checkbox is turned off, both the OS and recovery mode will be made unbootable and the command that opens the bootloader will not be allowed, which effectively renders the device hard bricked. The warning is repeated in capitals: always leave OEM unlocking enabled if rooted.

The logic is tight and worth understanding. A locked bootloader is what makes the device tamper resistant, and a custom root of trust key is what lets you sign your own images. Turning off OEM unlocking removes the escape hatch. Root, meanwhile, means something can write to the boot partition. The combination of a locked bootloader and root means a wrong image can be written and there is no way back, so the checkbox is the only recovery mechanism left, and it is the thing people disable because leaving it on means the device can always be unlocked.

The second warning covers any operation that causes an improperly signed boot image to be flashed, which results in the device being unbootable and unrecoverable without unlocking the bootloader again, and thus a data wipe. Two specific ways to do it are named, and both are common mistakes. The Direct install method for updating Magisk, because Magisk updates must be done by repatching the OTA rather than via the app. And the Uninstall Magisk feature in Magisk, because if root access is no longer needed, Magisk must be removed by repatching the OTA with the --rootless option rather than via the app.

And if the boot image has ever been modified, do not reboot. Open an issue for support and be very clear about what steps were done, because if Android is still running and root access works, recovery without a wipe might still be possible.

Editorial conclusion

Adopt avbroot if you keep a rooted Android device on the A/B partitioning scheme and want official system updates to keep working, because the tool does the part that is hard, which is re-signing the boot, vbmeta, payload and zip consistently so the bootloader accepts the result. Do not adopt it on a device whose bootloader you cannot open, because the whole flow depends on custom root of trust keys and there is no recovery path if it goes wrong. Before you patch anything, read the warnings section in full, particularly the OEM unlocking rule, and generate a separate key set per device so an OTA for one phone cannot be flashed to another.

Frequently asked questions

Official sources

1. chenxiaolong/avbroot on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases