mtk-gpt-tool

Build, patch, inspect, and reverse-engineer MediaTek GPT partition images (PGPT.img / SGPT.img) from scatter XML files or plain partition-table text.

Install

git clone https://github.com/anomalyco/mtk-gpt-tool.git
cd mtk-gpt-tool
pip install -e .

Quick start

# Inspect a real device GPT
mtk-gpt inspect --pgpt PGPT.img --sector-size 4096

# Generate fresh GPT images from a scatter file
mtk-gpt generate --scatter MT6789_Android_scatter.xml --storage ufs \
  --disk-size 512GB -o ./out

# Patch existing GPT with new partition boundaries
mtk-gpt patch --scatter MT6789_Android_scatter.xml --storage ufs \
  --pgpt PGPT.img --sgpt SGPT.img --disk-size 512GB -o ./out

# Reconstruct scatter XML from a real device GPT
mtk-gpt to-scatter --scatter template.xml --storage ufs \
  --pgpt PGPT.img --sector-size 4096 -o ./reconstructed

Subcommands

Partition table file (--partitions)

Define partitions in a text file instead of a scatter XML. Two formats are supported and auto-detected.

3-column format

# name  first_lba  last_lba
boot    174592     190975
system  2717696    124956663
vendor  358400     2717695

Values can be decimal or hex (0x...).

sgdisk format

Paste sgdisk --print output directly — header and footer lines are auto-skipped:

Number  Start (sector)  End (sector)  Size       Code  Name
   1             174592         190975   64.0 MiB  0700  boot_a
   2             313856         330239   64.0 MiB  0700  boot_b
   3             358400        2717695   9216.0 MiB 0700  super
   4            2717696      124956663   477.5 GiB  0700  userdata

Lines starting with # or blank lines are also ignored.

Full workflow

# 1. Dump your device partition table
sgdisk --print /dev/block/sda > partitions.txt

# 2. Generate fresh GPT images
mtk-gpt generate --partitions partitions.txt \
  --disk-size 512GB --sector-size 4096 -o ./my_gpt

# 3. Flash
fastboot flash PGPT ./my_gpt/PGPT.img
fastboot flash SGPT ./my_gpt/SGPT.img

Built-in example

If you place firmware files in bin/ (or point MTK_FW_DIR at the directory containing PGPT.img, SGPT.img, and MT6789_Android_scatter.xml):

# Run the full demo
mtk-gpt example

# Or specify a custom firmware directory
MTK_FW_DIR=/path/to/firmware mtk-gpt example

The example walks through all 7 steps: inspect → generate → verify → partition-table input → exclude → to-scatter round-trip → patch → config file.

Excluding partitions (--exclude)

Place selected partition entries beyond disk capacity so the OS ignores them. Partition names and GUIDs stay in the table (passes preloader checks) but reads to those LBAs fail.

# Disable GenieZone partitions
mtk-gpt generate --scatter scatter.xml --storage ufs \
  --disk-size 512GB --exclude gz_a,gz_b -o ./out

# Disable via partition table file
mtk-gpt generate --partitions my_parts.txt \
  --disk-size 512GB --sector-size 4096 \
  --exclude gz_a,gz_b,gz1,gz2 -o ./out

# Also works with patch
mtk-gpt patch --scatter scatter.xml --storage ufs \
  --pgpt PGPT.img --sgpt SGPT.img --disk-size 512GB \
  --exclude gz_a -o ./out

TOML config file

Save CLI flags to a .toml file and pass --config:

# mtk-gpt-tool.toml
scatter = "./MT6789_Android_scatter.xml"
storage = "ufs"
sector_size = 4096
disk_size = 511839305728

mtk-gpt generate --config mtk-gpt-tool.toml -o ./out

The tool also auto-discovers ./mtk-gpt-tool.toml and ./.mtk-gpt-tool.toml without --config.

Options reference

Common tasks