ubi_reader: extracting files from UBI and UBIFS images and rebuilding their parameters

Two directions: read the files out, or rebuild the image parameters

UBI Reader is a Python module and collection of scripts capable of extracting the contents of UBI and UBIFS images, along with analyzing these images to determine the parameter settings to recreate them using the mtd-utils tools.

That sentence describes two different jobs and it is worth separating them, because most people who find this tool want only the first.

The extraction direction is for forensic work. A NAND dump taken from a device is a blob, and the UBI and UBIFS structures inside it describe a filesystem. The scripts find that filesystem in the dump and pull the contents out so they can be listed, searched and read.

The reconstruction direction is the reverse. The utils_info script analyzes a UBI image and creates a Linux shell script and a UBI config file that can be used for building new UBI images to the same specifications. In other words, it recovers the layout parameters of an image so you can reproduce it with the kernel's own mtd-utils rather than with this tool.

That second capability is the more unusual one and the reason the project is more than a file carver. Recovering the exact settings that produced an image is what you need if you want to build a test image, reproduce a device configuration, or rebuild a partition for a device that expects a particular layout.

The audience is firmware and forensics people. The authors listed in the pyproject.toml are ONEKEY and Jason Pruitt, the project is maintained under the onekey-sec organisation, the licence is GPL-3.0, and the primary language is Python. The default branch is main and the current version is 0.8.16, released on 2026-09-04, after 0.8.15 in August 2026 and 0.8.14 in June 2026. The last push was on 2026-09-13.

Six console scripts, each with one job

The pyproject.toml registers six entry points, and the split is by task rather than by flag. Each one takes a path to a file containing UBI or UBIFS data and does a specific thing with it.

Extracting file contents is the main one.

ubireader_extract_files [options] path/to/file

The script searches for the first occurrence of UBI or UBIFS data in the file and attempts to extract the contents, so it should work with a NAND dump directly. Output goes to ./ubifs-root/ by default.

Listing and copying individual files is the second.

ubireader_list_files [options] path/to/file

This one treats the data as a UBIFS and lets you point at a path inside it, with -P and --path for the path to list and -C with --copy plus -D with --copy-dest to copy a file out to a local directory. The example given is copying /etc/passwd out of the image.

Extracting whole images is the third.

ubireader_extract_images [options] path/to/file

This extracts the whole UBI or UBIFS image from a NAND dump, or the UBIFS image from inside a UBI image. The -u and --image-type option selects UBI or UBIFS, and the default is UBIFS.

The parameter recovery script is the fourth.

ubireader_utils_info [options] path/to/file

The -r and --show-only option prints the options and values instead of writing the script and config file.

Displaying information is the fifth and block inspection is the sixth.

ubireader_display_info [options] path/to/file
ubireader_display_blocks [options] "{'block.attr':?, ...}" path/to/file

The display_info script shows UBI information plus header info from the layout block including volume table records, and for a UBIFS image the Super Node and both Master Nodes, with -u and --ubifs-info used to get the UBIFS info from inside a UBI file. The display_blocks script searches for blocks matching a Python dict of search parameters, and the README gives the example of finding PEBs 0, 1, 100, 101 and 102 with an erase count of 1 that are valid blocks.

The offset and block size options exist for damaged images

Most of the flags on these scripts exist for one reason: the image in front of you is not clean. A NAND dump is not a filesystem image, and the UBI data inside it can start at an unexpected address, or the tool can guess the wrong one.

The size options let you tell it rather than let it guess. The -p and --peb-size option specifies the PEB size of the UBI image, instead of having it guess, and -e and --leb-size does the same for the LEB size of a UBIFS image.

The offset options are the more interesting pair. The -s and --start-offset option tells the script to look for UBI or UBIFS data at a given address, and -n and --end-offset tells it to ignore data after a given address. And -g and --guess-offset specifies that the script should start guessing where the UBI data is in the file, which the README describes as useful for NAND dumps with false positives before the image.

Then there are the flags for tolerating damage. The -w and --warn-only-block-read-errors option attempts to continue extracting files even with bad block reads, with the honest caveat that some data will be missing or corrupted. The -i and --ignore-block-header-errors option forces unused and error containing blocks to be included, and also displayed with log or verbose output.

And -f and --u-boot-fix assumes blocks with image_seq 0 are there because of older U-boot implementations and includes them, with a warning that this may cause issues with multiple UBI image files.

The logging options are -l and --log for printing actions being taken while running, and -v and --verbose which the README describes as basically printing everything about anything happening. Output location is -o and --output-dir, which overrides the default of ubi_reader/output.

Together these flags describe a tool written by people who have worked on images that did not extract cleanly the first time.

Known issues state exactly what you will not get

The Known Issues section is short and unusually concrete, and it should be read before you plan an investigation around this tool.

The first is the journal. This does not replay the journal, so uncommitted data will not be retrieved. Data can be in the journal with both clean and unclean shutdowns.

That sentence carries two implications. A clean shutdown does not mean the journal is empty, so a device that powered down properly may still have data sitting in the journal that you will not see. And an unclean shutdown may have left more there. If you are looking for the last file a device wrote before it died, the journal is exactly where it would be, and this tool will not recover it.

The second is error correction. Depending on how the NAND was dumped, the data bits may not be error corrected. This is a property of the dump rather than of the tool, but it means the tool cannot promise the extracted content is bit accurate for a dump taken without ECC handling.

The third is special files. Socket files will be ignored, and the fix is to change ubireader/settings.py to have the tool create dummy files in their place.

The socket handling has an operational consequence too. If the image includes special files, you will need to run as root or sudo for it to create these files, and without that it will skip them and show a warning that these files were not created.

So the tool tells you what is missing rather than silently producing a short result, which is the right behaviour, and it also means a silent extraction is not proof that the filesystem was empty.

The testing branch is a separate tool for broken images

There is a branch dedicated to damaged images, and the README is clear that it is a different thing rather than a staging area.

The testing branch includes a tools/ directory with scripts to help when trying to extract data from broken images. These also serve as examples of how to use parts of ubi_reader in custom scripts, which is the more durable of the two purposes: the branch doubles as worked examples of driving the library yourself.

The branch also includes an override system for manually setting certain parameters that may be reported wrong by the UBI or UBIFS data. That is the mechanism for the case where the header of a corrupted image says one thing and the blocks say another.

The README states that this branch will probably remain separate, as it is meant to be customized to aid in extracting data from problematic images. And it gives the install method for it: python setup.py develop, which makes it easier to modify ubi_reader as needed.

That last point matters for the practical workflow. The main branch is the one you install from PyPI or with poetry, and you treat it as a fixed tool. The testing branch is the one you check out and edit in place, so that the overrides reflect the specific image in front of you. A forensic analyst working a broken image would likely keep the testing branch checked out locally, adjust the settings, and treat that checkout as the tool for that case.

That split is also a maintenance consideration. A branch that is meant to be customised does not track the main branch, so changes to the main line do not flow into it and any local modification is yours to maintain.

Where ubi_reader is the wrong tool

The first wrong-tool case is a live device. Every script takes a path to a file. If you want to read the UBI partition on a running system, mtd-utils and the kernel's own tooling are the route, and this tool is for images you already have as files.

The second case is a filesystem other than UBIFS inside UBI. The tool covers the two structures it was written for. A device with a different flash filesystem, or with a plain ext4 or squashfs partition, is not what these scripts parse.

The third case is an investigation that hinges on the journal or on bit-level accuracy. Both are named in the Known Issues. If the question is what was the device doing immediately before it stopped, the unflushed journal is usually where the answer is, and this tool will not show it to you.

The fourth case is someone expecting to replace mtd-utils. The utils_info script produces a shell script and a UBI config file for building new UBI images to the same specifications, and those outputs are consumed by the mtd-utils tools. The tool reconstructs the parameters and hands them to another toolchain; it does not become the image builder.

There is also a packaging nuance to note. The pyproject.toml names the distribution ubi-reader while the import package is ubireader and the scripts are all prefixed ubireader_, so an install by hand has three slightly different names to keep straight, and pip install --user ubi_reader in the README resolves to the hyphenated distribution.

The dependency set is small and worth knowing for an offline environment: lzallright for the LZO variant UBIFS uses, cryptography, and zstandard. The pytest configuration runs coverage over both the ubireader package and the tests directory with branch coverage and a fail-under of 90, and vulture is configured to look for dead code across the package, the scripts directory and a whitelist file, which is a reasonable sign that the codebase is kept tidy.

Editorial conclusion

ubi_reader suits a firmware analyst or incident responder who has a NAND dump and needs the file system contents out of it, since the scripts cover extraction, browsing, block inspection and parameter recovery, and the offset and block-size options exist for damaged images. It does not suit a live device workflow, because it works on an image file rather than on a mounted partition, and it does not replace mtd-utils, it derives parameters to feed them. Before adopting, read the Known Issues section first: the journal is not replayed, so uncommitted data will not be recovered, and NAND data bits may not be error corrected depending on how the dump was taken.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. onekey-sec/ubi_reader on GitHub
4. README
5. Releases