Installation
Install ipa-forge from PyPI and run your first patch in under a minute.
ipa-forge is a published PyPI package. You don't need to clone the repository to use it — that's only needed if you're building patch definitions alongside their assets in a git-tracked project, or contributing to the engine itself.
Install
pipx installs forge as an isolated, globally
available command — the standard way to install a Python CLI tool
without touching your other projects' environments.
pipx install ipa-forgeEither way, this installs the forge command:
forge --versionSigning needs macOS
forge inspect, forge validate, forge patch --dry-run, and forge analysis work on any OS. Real signing (forge patch without --dry-run)
shells out to Apple's codesign/security and requires macOS with Xcode
Command Line Tools (xcode-select -p should print a path).
Requirements
Prop
Type
Verify it works
No app of your own needed yet — the repository ships a synthetic test fixture you can patch immediately after installing:
curl -LO https://raw.githubusercontent.com/nandan-varma/ipa-forge/main/fixtures/synthetic_app.ipa
curl -LO https://raw.githubusercontent.com/nandan-varma/ipa-forge/main/fixtures/patches/example.yaml
mkdir -p assets && curl -Lo assets/patched_asset.txt \
https://raw.githubusercontent.com/nandan-varma/ipa-forge/main/fixtures/patches/assets/patched_asset.txt
forge inspect synthetic_app.ipa
forge patch --ipa synthetic_app.ipa --patches example.yaml \
--output /tmp/patched.ipa --dry-runA clean Dry run OK confirms the install works end to end, no signing
identity required.
Next steps
Usage
The forge CLI and web GUI, end to end
Patch Reference
Write your own patch definition YAML
Adding a New App
Build a complete patch set for an app you want to modify
Installing from source
Only needed to develop ipa-forge itself
Contributing to the engine (a new patch operation type, a signing provider, a bug fix) needs an editable install against a clone of the repository — regular usage never does.
git clone https://github.com/nandan-varma/ipa-forge.git
cd ipa-forge
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest tests/See Architecture and Extensibility before making engine changes.