twrpdtgen derives a TWRP device tree from a stock recovery image

The input is a stock image, the output is a device tree folder

The name says what the tool does: it creates a TWRP compatible device tree only from an Android recovery image of the device's stock ROM, or from a boot image if the device uses non-dynamic partitions with A/B. That restriction is the whole point. A device tree for a custom recovery describes partitions, paths and mount points, and hand writing one means reading them out of the stock image yourself. The tool reads that image and produces the tree, so the tedious part is delegated to a script rather than to a careful human. The documentation states the script has been confirmed to support images built starting from Android 4.4 up to Android 12, which is a real and useful boundary to know before you start. The project describes itself as a Python library and script for automatically generating a TWRP compatible device tree from a boot or recovery image, and it is published on PyPI as twrpdtgen.

Python 3.8 and a cpio binary on Linux

The requirements are short. The tool requires Python 3.8 or greater, and the packaging metadata agrees, with the Python constraint declared as ^3.8. There is one system level dependency that catches people out, and it is documented plainly: Linux only, be sure to have cpio installed in your system, with the installation given as apt install cpio or pacman -S cpio depending on the package manager. The reason cpio matters is not a detail the project explains, but the requirement stands: unpacking a recovery image needs a tool that can handle the cpio archives such images carry, and the script does not bundle one. That also means the tool does not run on macOS or Windows without a cpio implementation, which narrows the audience to Linux users who are already comfortable with a recovery build environment. Everything else is handled by Python packages.

One command produces output/manufacturer/codename

The command line use is a single invocation, and the module runs as a Python module rather than through a separate entry point in the documented example:

python3 -m twrpdtgen <path to image>

You pass the path to the image, and when everything goes well there is a device tree at output/manufacturer/codename, which is the layout TWRP expects, with the manufacturer and codename directories taken from the image itself. The packaging metadata also declares a console script entry point named twrpdtgen pointing at twrpdtgen.main:main, so a pip install puts a twrpdtgen command on the path as well. The installation is a single pip install:

pip3 install twrpdtgen

The project is built with Poetry, since the packaging configuration lives in pyproject.toml with a poetry-core build backend, and a poetry.lock file pins the dependency versions for that project. The runtime dependencies are GitPython, Jinja2 and sebaubuntu-libs, and the project lists Jinja as its primary language, which fits a tool that produces its output through templates rather than by assembling raw text.

The DeviceTree class gives you the same data inside a script

The tool is described as a library and a script, and the library entry point is the DeviceTree class in the device_tree module. The documented usage is short enough to see the shape of the API:

from twrpdtgen.device_tree import DeviceTree

# Get image info
device_tree = DeviceTree(image_path)

# Dump device tree to folder
device_tree.dump_to_folder(output_path)

Two things follow from that. Constructing the object with the image path gives you the parsed image information, and dumping to a folder is a separate call with an explicit output path, so a script that wants to inspect the result before writing it can do so. This matters for automation. A device maintainer who wants to generate trees for a batch of images, or a build script that regenerates a tree when a new stock ROM lands, can call the module rather than shelling out and parsing files afterwards. It also means the tool can be tested, because the parse step and the write step are separated rather than fused into one command.

Where the tool stops working

The limits are specific and worth reading before you invest an evening. The first is the Android range, from images built starting from Android 4.4 up to Android 12, so a device on a newer platform is outside the confirmed support even if the script appears to run. The second is the image kind. The documented inputs are a recovery image, or a boot image when the device uses non-dynamic partitions with A/B, which means a device that expects a boot image but uses dynamic partitions falls into a gap the tool does not describe. The third is the platform, since cpio and the Linux assumption rule out other operating systems. The fourth is the nature of the output. A generated device tree is a starting point for a recovery build, not a finished one, and the project does not claim otherwise. The README is short and does not document a verification procedure, so the practical expectation has to be that you compare the generated tree against the stock configuration yourself before you rely on it.

Apache-2.0 in the packaging, an unknown licence field in the repository

Licence handling here needs a sentence of care, because the two sources do not match. The licence field on the repository is not filled in, while the packaging configuration in pyproject.toml declares the licence as Apache-2.0 and names Sebastiano Barezzi as the author. The README carries a notice in a code block that credits the copyright of 2022 to The Android Open Source Project with an SPDX-License-Identifier of Apache-2.0. So the code carries an Apache-2.0 notice, and the project metadata agrees, but anyone relying on the repository header alone would see nothing. That is a documentation gap rather than a dispute. On releases, the repository has no GitHub releases at all, so the version to depend on is the one on PyPI, which the packaging configuration gives as 3.0.0. The repository is not archived, the last push was on 2026-10-19, and the topics list includes hacktoberfest, which is consistent with a project that takes outside contributions.

Editorial conclusion

Adopt twrpdtgen when you are bringing up a custom recovery for a device whose stock recovery image you already have, because the tool removes the manual transcription of partitions, fstab entries and paths that normally takes hours and is easy to get subtly wrong. Do not expect it to cover devices whose boot images it cannot parse, to work on macOS or Windows, or to produce a tree that is finished, since the generated output still needs checking against the device. Before you rely on it, confirm your image is one of the supported formats, install cpio so the image can be unpacked, and read the generated tree against the stock fstab before flashing anything.

Frequently asked questions

Official sources

1. Issues
2. README
3. twrpdtgen/twrpdtgen on GitHub