Introduction
Documentation index for ipa-forge, a data-driven iOS IPA patcher for AltStore Classic sideloading.
ipa-forge extracts a user-supplied .ipa, applies version-aware patches
declared in external YAML — binary byte patches, resource replace/add/remove,
plist edits, dylib injection — and re-signs the result into a
standard-structure .ipa that AltStore Classic can install and refresh.
It's published on PyPI (pipx install ipa-forge) — cloning this repository
is never required just to use it. Pick a starting point below.
I want to...
Install ipa-forge
pipx/pip install from PyPI, verify it works — under a minute
Use the CLI or GUI
forge patch, forge hooks, forge gui — full command reference
Write a patch definition
Every operation type, field, and matching rule in the target/patches/hooks YAML
Port a new app
The end-to-end playbook: new IPA, new bundle id, from zero to a working patch set
Add a feature
Conventions for adding a feature to an existing hook dylib
Reverse engineer an IPA
forge analysis: class-dump, strings, symbols, security posture, version diffing
Fix an error
Every error message mapped to its cause and fix
Test on a real device
The manual AltStore Classic install/refresh checklist
Understand the engine
Component map, the 17-stage pipeline, hard constraints
Extend the engine
Add a new patch operation type or signing provider
Cut a release
PyPI Trusted Publishing and GitHub Releases via CI
Patch sets are not part of this repo
The engine is app-agnostic — it understands patch operation types, never a
specific bundle id or byte pattern. Any app-specific patch set (the YAML
definition plus, optionally, a hook dylib) lives entirely outside this repo,
under a patches/<app>/ directory you provide yourself; ipa-forge ships no
patch definitions or reverse-engineered specifics for any third-party app.
See Adding a New App for the shape a patch set follows.
Reading order for a new project
Install
Installation — pipx install ipa-forge, then
forge --version to confirm.
Learn the CLI/GUI
Usage covers forge patch, forge hooks, and forge gui
end to end — this is the primary way most people use ipa-forge.
Build a patch set (optional)
Adding a New App if the task is "here's an IPA, port everything," or just Patch Reference if you only need the YAML contract.
When something breaks
Troubleshooting maps every error message to its cause and fix.