ipsw

iOS/macOS Research Swiss Army Knife

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

Use ipsw with an AI agent

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.

Install

macOS

The maintainer's Homebrew tap includes the extras build:

brew install blacktop/tap/ipsw

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

Linux

sudo snap install ipsw

Windows

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.

What you can do

| Area | Tools | | --- | --- | | Firmware | Download IPSWs, OTAs, macOS installers, Xcode, and KDKs; extract components and compare builds | | Mach-O | Inspect load commands, symbols, signatures, and entitlements; disassemble ARM64 code | | dyld shared caches | Find symbols and cross-references, extract dylibs, dump Objective-C headers, and inspect Swift metadata | | Kernel | Extract KEXTs, inspect syscalls and symbols, and compare kernelcaches | | Firmware components | Parse IMG4, decrypt AEA archives, and inspect iBoot and coprocessor firmware | | Devices | List devices and apps, transfer files with AFC, capture logs, and mount developer images | | App Store Connect | Manage certificates, bundle IDs, devices, and provisioning profiles | | Research | Symbolicate crash logs, debug over SSH, trace with Frida, and decompile with an LLM |

CLI examples

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

Download and extract firmware

# 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

Explore a dyld shared cache

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.

Inspect binaries and kernelcaches

# 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

Work with a connected device

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

Decompile with an LLM

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.

Configuration and automation

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.

Documentation and community

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

Build and contribute

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.

Credits

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.

License

MIT.