MysticGSI

A tool to build a GSI (Generic System Image) from stock Android firmware.

Supported firmware:

full OTA zips (payload.bin)
fastboot packages
super.img, sparse images
system.new.dat
Samsung tars
Huawei UPDATE.APP
Unisoc .pac
LG .kdz
Oppo .ozip
QFIL packages
Sony .sin
Pixel factory images

Partitions can be ext4, EROFS or F2FS.

Setup

This project requires Python 3.10+.

On macOS, install Homebrew and Xcode Command Line Tools first.

Automatic setup

git clone https://github.com/MysticGSI/mysticgsi.git && cd mysticgsi
./setup_host.py     # --dev also installs pytest and Ruff

The script installs the system packages, creates .venv and makes sure mke2fs.android and e2fsdroid are available (building them if needed).

Manual setup

Swap requirements.txt for requirements-dev.txt if you want the dev tools.

macOS

xcode-select --install
brew install python@3.13 cmake ninja pkgconf erofs-utils brotli lz4 \
    pcre2 libusb zstd protobuf aria2 apktool gpatch openssl@3
"$(brew --prefix python@3.13)/bin/python3.13" -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python tools/build_android_tools.py

Ubuntu / Debian

sudo apt-get install python3 python3-venv erofs-utils aria2 patch \
    default-jre-headless curl build-essential cmake ninja-build pkg-config \
    perl golang-go libgtest-dev libusb-1.0-0-dev libpcre2-dev \
    libprotobuf-dev protobuf-compiler libbrotli-dev liblz4-dev libzstd-dev \
    libarchive-tools openssl
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python tools/build_android_tools.py

Then install apktool.

Arch

sudo pacman -Syu --needed python erofs-utils aria2 patch \
    jre-openjdk-headless android-tools curl openssl
python -m venv .venv
.venv/bin/python -m pip install -r requirements.txt

Then install apktool, or android-apktool-bin from the AUR (it needs jre-openjdk in place of jre-openjdk-headless).

NixOS

nix develop
python3 cli.py build <name> <firmware> --type <type>

apktool on Linux

Grab the latest apktool_<version>.jar from the releases:

mkdir -p ~/.local/bin
curl -fL -o ~/.local/bin/apktool.jar \
    https://github.com/iBotPeaches/Apktool/releases/download/v<version>/apktool_<version>.jar
printf '#!/bin/sh\nexec java -jar "$HOME/.local/bin/apktool.jar" "$@"\n' \
    > ~/.local/bin/apktool
chmod +x ~/.local/bin/apktool
export PATH="$HOME/.local/bin:$PATH"

Usage

.venv/bin/python cli.py build <name> <firmware|URL> [--type <type>] [--compress]
.venv/bin/python cli.py rebuild <name> [--compress]
.venv/bin/python cli.py list
.venv/bin/python cli.py clean

Commands

build - Build a new ROM image
rebuild - Rebuild an existing ROM image
list - List all builds
clean - Clean up all builds

Command-line options

name - Name of the build
firmware or URL - Path to the firmware or URL to download it from
--type <type> - ROM type; default is auto (use an explicit type if detection fails)
--compress - Compress the output image into a ZIP
--add <tag> - Add a tag to the build name
--no-debloat - Keep the apps the patch set would otherwise remove
--avb-key /path/to/key.pem - Sign with the specified RSA private key

By default, an image is signed with AOSP's AVB RSA-2048 test key. You can pass --avb-key /path/to/key.pem to sign with your own RSA private key.

Example:

.venv/bin/python cli.py build raven \
    https://dl.google.com/dl/android/aosp/raven-up1a.231105.003-factory-76a795d5.zip \
    --type pixel --compress

Development

See CONTRIBUTING.md before opening a pull request.

.venv/bin/python -m pytest tests -q
.venv/bin/ruff check .

Patch files of 50 MiB or more are stored xz-compressed (<name>.xz) and unpacked during builds. After adding one, run ./tools/assets.py pack and commit the .xz files (or .xz.000, .xz.001, ... for split archives).

./tools/assets.py status shows what's packed.

License

Apache License 2.0, see LICENSE. Bundled avbtool is MIT-licensed; see tools/avb/LICENSE. Third-party files under patches/ have separate terms; see NOTICE.

MysticGSI/mysticgsi

Star growth

README