ubi-reader

0.8.13 verified Sat May 09 auth: no python

A Python library to extract files from UBI (Unsorted Block Images) and UBIFS (UBI File System) images. Supports UBI headers, volumes, and UBIFS nodes. Latest version 0.8.13 (requires Python >=3.10). Released about once every few months.

pip install ubi-reader

Common errors

error AttributeError: module 'ubireader' has no attribute 'UBI' ↓

cause Incorrect import: using ubi-reader (hyphen) or importing wrong module.

fix

Use: from ubireader import UBI

error TypeError: extract_files() missing 1 required positional argument: 'output_path' ↓

cause extract_files requires an output path as second argument.

fix

call: extract_files(volume, 'output_dir')

error Construct.core.ExplicitError: Error in parsing field ... ↓

cause Image may be corrupted or not a valid UBI image.

fix

Verify image integrity (e.g., using mtd-utils ubiinfo).

Warnings

gotcha The library does not handle UBI images with encryption or compression other than LZO (if supported by construct). Ensure image is raw or LZO compressed. ↓

fix Pre-decompress the image if using other algorithms.

gotcha extract_files expects a volume object, not the whole UBI object. Common mistake: passing the UBI object directly. ↓

fix Iterate over ubi.volumes and pass each volume of type 'UBIFS' to extract_files.

deprecated The old API ubireader.UBI.extract_all() is deprecated in favor of per-volume extraction. ↓

fix Use extract_files from ubireader.ubifs for UBIFS volumes.

gotcha The library only reads UBI images, not UBIFS images directly. To handle a standalone UBIFS image, you must wrap it in a minimal UBI structure or use an alternative. ↓

fix Use ubireader.ubifs only for UBIFS volumes inside UBI images.

Imports

UBI

wrong

from ubi_reader import UBI

correct

from ubireader import UBI

Package name uses underscore, not hyphen.

extract_files

wrong

from ubireader import extract_files

correct

from ubireader.ubifs import extract_files

extract_files is a function in the ubifs submodule.

Quickstart

Load a UBI image and extract UBIFS volume contents to a directory.

from ubireader import UBI
from ubireader.ubifs import extract_files
from ubireader.ubifs.output import extract_common

with open('image.ubi', 'rb') as f:
    ubi = UBI(f)
    for volume in ubi.volumes:
        if volume.type == 'UBIFS':
            extract_files(volume, 'output_dir')