IPSW Parser

1.6.0 · active · verified Thu Apr 16

ipsw-parser is a Python 3 utility for parsing and extracting data from Apple IPSW (iPhone Software) firmware files. It provides programmatic access to various components within an IPSW, such as kernelcaches, build manifests, and device class hashes (DSC). The library is actively maintained with frequent minor updates, currently at version 1.6.0.

Common errors

```
ModuleNotFoundError: No module named 'ipsw_parser'
```
cause The `ipsw-parser` package is not installed in your current Python environment, or there is a typo in the import statement.

fix Ensure the package is installed using `pip install ipsw-parser`. Verify your import statements, typically `from ipsw_parser.ipsw import IPSW`.
```
FileNotFoundError: [Errno 2] No such file or directory: 'path/to/your/firmware.ipsw'
```
cause The specified path to the IPSW file does not exist or is incorrect. This often happens when the file is moved, deleted, or the path contains typos.

fix Double-check the file path. Ensure the IPSW file exists at the given location and that the path is absolute or correct relative to your script's working directory.
```
ipsw_parser.exceptions.IPSWError: This is not an IPSW file.
```
cause The file provided to the `IPSW` constructor is either corrupted, incomplete, or not a valid Apple IPSW firmware archive.

fix Verify that the file you are trying to parse is a legitimate IPSW file. You might need to download a fresh copy or check its integrity. The file extension should typically be `.ipsw`.
```
TypeError: 'module' object is not callable
```
cause You might be trying to call a module directly instead of a class or function within it, for example, `ipsw_parser.ipsw()` instead of `ipsw_parser.ipsw.IPSW()`.

fix Ensure you are instantiating the `IPSW` class correctly, e.g., `from ipsw_parser.ipsw import IPSW; ipsw = IPSW('file.ipsw')`.

Warnings

breaking Starting with version 1.4.0, functionality previously included in `ipsw-parser` was moved into the `pymobiledevice3` library. If your code relied on specific functions or classes that are no longer present, you will encounter `AttributeError` or `ModuleNotFoundError`.
Fix: Review the `pymobiledevice3` library documentation and integrate it into your project if you require the moved functionality. Check the changelog for specific removals.
breaking Support for Python 3.8 was officially removed in version 1.3.8. Attempting to use `ipsw-parser` on Python 3.8 or older will result in installation issues or runtime errors.
Fix: Upgrade your Python environment to Python 3.9 or newer. The library's `requires_python` metadata explicitly states `>=3.9`.
gotcha In version 1.5.0, the internal logic for DSC (Device Class Hash) extraction was refactored and split into its own module. While the top-level `ipsw.extract_dsc()` method should remain stable, direct imports to internal DSC-related functions might require updates.
Fix: Prefer using the `IPSW` object's methods (e.g., `ipsw.extract_dsc()`) rather than directly importing internal DSC modules. If you must use internal modules, consult the source code for the correct new paths.

Install

pip install ipsw-parser Install latest version

Imports

IPSW
```
from ipsw_parser.ipsw import IPSW
```

IPSWError

from ipsw_parser.exceptions import IPSWError

Quickstart

This quickstart demonstrates how to initialize the `IPSW` parser with a firmware file, retrieve basic information like the device class and build ID, and extract common components such as the kernelcache and device class hashes (DSC).

from ipsw_parser.ipsw import IPSW
from ipsw_parser.exceptions import IPSWError
import os

# For demonstration, assume an IPSW file exists or is specified via environment variable.
# Replace 'path/to/your/firmware.ipsw' with an actual path to an IPSW file.
# You can often find these files on websites like ipsw.me
ipsw_file_path = os.environ.get('IPSW_FILE_PATH', 'path/to/your/firmware.ipsw')

if not os.path.exists(ipsw_file_path):
    print(f"Warning: IPSW file not found at '{ipsw_file_path}'. Please provide a valid path.")
    print("Skipping quickstart example as no IPSW file is available.")
else:
    try:
        # Initialize the IPSW parser with the file path
        ipsw = IPSW(ipsw_file_path)
        print(f"Successfully loaded IPSW from: {ipsw.path}")

        # Access basic information
        print(f"Device Class: {ipsw.build_identity.device_class}")
        print(f"Build ID: {ipsw.build_identity.build_id}")

        # Example: Extract the kernelcache
        # This will extract to a default temporary location or specified directory
        kernel_path = ipsw.extract_kernelcache()
        print(f"Kernelcache extracted to: {kernel_path}")

        # Example: Extract the device class hashes (DSC) if available
        # Note: In v1.5.0+, dsc extraction logic was moved to a separate module.
        # This example uses the primary IPSW object method which wraps the new logic.
        dsc_path = ipsw.extract_dsc()
        if dsc_path:
            print(f"Device Class Hashes (DSC) extracted to: {dsc_path}")
        else:
            print("No DSC found or extracted.")

    except IPSWError as e:
        print(f"Error parsing IPSW file: {e}")
    except FileNotFoundError:
        print(f"Error: The specified IPSW file '{ipsw_file_path}' was not found.")
    except Exception as e:
        print(f"An unexpected error occurred: {e}")

view raw JSON →