payload-dumper-rust 🦀

A fast and efficient Android OTA payload dumper.

What it does

Extracts partition images (boot, system, vendor, etc.) from Android OTA payload.bin files.

This has these features

Parallel extraction - Uses all CPU cores for faster extraction
Works with ZIP files - Extract directly from ROM ZIPs without unzipping first
URL support - Extract from remote URLs, downloading only the needed data instead of the entire file
Cross-platform - Works on Linux, Windows, macOS, and Android (Termux)
Incremental OTA - Experimental Incremental OTA Support ( Not tested)

Installation

Quick Install

Linux / macOS / Termux:

bash <(curl -sSL "https://raw.githubusercontent.com/rhythmcache/payload-dumper-rust/main/scripts/install.sh")

Windows (PowerShell):

powershell -NoExit -ExecutionPolicy Bypass -Command "Invoke-RestMethod -Uri 'https://raw.githubusercontent.com/rhythmcache/payload-dumper-rust/main/scripts/install.ps1' | Invoke-Expression"

Pre-built Binaries

Download from releases.

Build from Source

cargo install payload_dumper

Or:

git clone https://github.com/rhythmcache/payload-dumper-rust
cd payload-dumper-rust
cargo build --release

Usage

Basic Examples

Extract from payload.bin:

payload_dumper payload.bin -o output

Extract from ROM ZIP (no unzipping required):

payload_dumper rom.zip -o output

Extract from URL (downloads only required data):

payload_dumper https://example.com/ota.zip -o output

Extract specific partitions:

payload_dumper payload.bin -i boot,vendor_boot -o output

Extract Incremental OTA:

To extract an incremental OTA, create a directory named old in the current working directory and copy all images from the previous build into it.
If the old images are located elsewhere, specify their location using the --source-dir <PATH> argument.

List partitions without extracting:

payload_dumper payload.bin --list

Advanced Options

URL extraction with prefetch (better for slow connections):

payload_dumper https://example.com/ota.zip --prefetch -o output

Custom thread count:

payload_dumper payload.bin -t 8 -o output

Export metadata as JSON:

payload_dumper payload.bin --metadata -o output
# Creates output/payload_metadata.json

Full metadata with operation details:

payload_dumper payload.bin --metadata=full -o output

Skip verification (faster but not recommended):

payload_dumper payload.bin --no-verify -o output

All Options

Usage: payload_dumper [OPTIONS] <PAYLOAD_PATH>

Arguments:
  <PAYLOAD_PATH>  Path to payload.bin, ROM ZIP, or URL

Options:
  -o, --out <OUT>              Output directory [default: output]
  -U, --user-agent <AGENT>     Custom User-Agent for HTTP requests
  -C, --cookies <COOKIES>      Custom HTTP Cookie header value for remote requests
      --dns <DNS>              Custom DNS servers (comma-separated IPs)
  -i, --images <IMAGES>        Comma-separated partition names to extract
  -t, --threads <THREADS>      Number of threads for parallel processing
  -l, --list                   List available partitions
  -m, --metadata[=<MODE>]      Save metadata as JSON (compact or full)
  -P, --no-parallel            Disable parallel extraction
  -n, --no-verify              Skip hash verification
      --prefetch               Download all data first (for remote URLs)
  -q, --quiet                  Suppress all non-essential output (errors will still be shown)
  -h, --help                   Show help
  -V, --version                Show version

Why extract from URLs?

Instead of downloading a 3GB OTA file to extract a 50MB boot image, this tool downloads only ~50-100MB of required data.

Useful for:

Quick partition extraction without full downloads
CI/CD pipelines
Bandwidth-limited connections

Build

To build manually, you will need:

Rust compiler and Cargo
Basic command-line knowledge
A bit of patience

1. Clone the repository

git clone --depth 1 https://github.com/rhythmcache/payload-dumper-rust.git
cd payload-dumper-rust

2. Default build (recommended for most users)

cargo build --release

This builds the binary with:

Local .bin and .zip support
Remote HTTP/HTTPS support
Prefetch mode
Metadata support

Feature-based builds

Payload Dumper is modular. You can disable features you do not need to:

Reduce compile time
Reduce binary size
Avoid unnecessary dependencies

Local files only (fastest build, smallest binary)

If you only need local payload files and no network support:

cargo build --release --no-default-features

This:

Disables all HTTP/network code
Removes reqwest, DNS, and TLS dependencies
Compiles much faster
Produces a significantly smaller binary

Enable remote (HTTP/HTTPS) support

To work with remote URLs:

cargo build --release --features remote_zip

Static binaries and DNS notes

When building a fully static binary (for example with musl), DNS resolution may fail because system libc DNS resolvers are unavailable.

Use the built-in DNS resolver

cargo build --release --features hickory_dns

This enables:

Built-in DNS resolution via hickory-resolver
No dependency on system libc DNS
Reliable behavior in fully static environments

By default, the resolver uses Cloudflare DNS (1.1.1.1).

Override DNS server at runtime

The DNS server is selected at runtime.

You can override it in two ways:

1. Using environment variable

export PAYLOAD_DUMPER_CUSTOM_DNS=8.8.8.8,4.4.4.4
./payload_dumper <PAYLOAD>

2. Using CLI flag (--dns)

./payload_dumper --dns 8.8.8.8,4.4.4.4 <PAYLOAD>

If both are provided, the --dns flag takes precedence.

If you are unsure, use the default build.

Troubleshooting

"Server doesn't support range requests"
Download the file first, then extract locally.

Out of memory errors
Use --no-parallel or reduce thread count with -t.

Slow extraction
Remove --no-parallel if set. For remote extraction, try --prefetch.

Credits

Inspired by vm03/payload_dumper

License

Apache-2.0

payload_dumper 0.8.3