blacktop/ipsw

ipsw is a command-line toolkit for Apple firmware research and reverse engineering. Download and unpack IPSWs and OTAs, inspect Mach-O binaries and dyld shared caches, analyze kernelcaches, and work with connected iOS devices.

Agent skill · Install · CLI examples · Documentation

Start with ipsw-skill if you're working in Claude Code, Codex, Gemini CLI, or another agent that supports skills. It gives the agent command references and workflows for firmware extraction, binary analysis, and Apple platform research.

Install the ipsw CLI, then add the skill:

npx skills add https://github.com/blacktop/ipsw-skill --skill ipsw

You can then ask for a task in plain language. For example:

Download the latest IPSW for iPhone 15 Pro and extract its kernelcache.

Dump the Objective-C headers for SpringBoardServices from this dyld shared cache.

Compare the KEXTs in these two kernelcaches.

The skill README has setup instructions for individual agents, including the Claude Code plugin and Gemini CLI extension.

The maintainer's Homebrew tap includes the extras build:

brew install blacktop/tap/ipsw

The Homebrew core formula is also available: brew install ipsw.

sudo snap install ipsw

scoop bucket add blacktop https://github.com/blacktop/scoop-bucket.git
scoop install blacktop/ipsw

You can also download binaries from GitHub Releases. See the installation guide for other packages and optional dependencies. Some commands depend on the host OS or build variant; Frida support, for example, has a separate build.

Replace the example file paths with your own. Run ipsw --help or add --help to any subcommand for its options.

# Download the latest IPSW for iPhone 15 Pro
ipsw download ipsw --device iPhone16,1 --latest

# Inspect a local IPSW and extract its kernelcache
ipsw info /path/to/firmware.ipsw
ipsw extract --kernel /path/to/firmware.ipsw

# Compare two firmware builds
ipsw diff /path/to/old.ipsw /path/to/new.ipsw

ipsw dyld info /path/to/dyld_shared_cache_arm64e

# Extract Foundation for use in other tools
ipsw dyld extract /path/to/dyld_shared_cache_arm64e Foundation

# Dump headers directly from the cache
ipsw class-dump /path/to/dyld_shared_cache_arm64e SpringBoardServices --headers -o headers

Use the cache directly for Objective-C analysis: extracted dylibs can still reference metadata stored elsewhere in the cache.

# Select an architecture explicitly for universal binaries
ipsw macho info /path/to/binary --arch arm64e
ipsw macho disass /path/to/binary --arch arm64e --symbol _main

# Search a directory of binaries for an imported symbol
ipsw macho search /path/to/binaries --import 'CCCrypt'

# List KEXTs, then extract one by its full bundle ID
ipsw kernel kexts /path/to/kernelcache
ipsw kernel extract /path/to/kernelcache com.apple.driver.ASIOKit -o kexts

ipsw idev list
ipsw idev apps ls
ipsw idev afc ls /
ipsw idev syslog

The macho disass and dyld disass commands can send disassembly to a configured LLM provider with --dec. See the decompiler guide for provider setup, model selection, and examples.

The CLI reads YAML configuration from ~/.config/ipsw/config.yaml; use --config to select another file. See config.example.yml and the configuration guide for settings and environment variables.

For scripts, select an architecture with --arch when opening universal binaries and use a full dylib path when a short name is ambiguous. Commands that support --json document it in their help.

The separate ipswd daemon exposes a REST API for automation. See the API reference.

• Agent skill and setup
• Guides and command reference
• Precomputed firmware diffs
• GitHub Discussions
• Issue tracker
• DeepWiki, an AI-generated guide to the codebase

When reporting a bug, include ipsw version, the command you ran, and the relevant firmware build or file type. Redact personal information from logs and crash reports.

Building from source requires Go 1.26 or later and a C toolchain for CGO:

git clone https://github.com/blacktop/ipsw.git
cd ipsw
make build

See CONTRIBUTING.md for development and contribution guidelines.

Thanks to Jonathan Levin for his tools and iOS internals documentation, the Apple security research community, and everyone who contributes code, bug reports, and research.

MIT.