PyIMG4

0.8.8 · active · verified Thu Apr 16

PyIMG4 is a Python library and CLI tool designed for parsing, manipulating, and creating Apple's proprietary Image4 format, including IMG4, IM4M (manifest), and IM4P (payload) files. It is currently at version 0.8.8 and maintains a relatively active release cadence, with updates addressing bugs, adding features, and refining internal logic.

Common errors

```
ModuleNotFoundError: No module named 'pyimg4' (or 'pyimg4 is not installed')
```
cause PyIMG4 is not installed in the active Python environment, or the environment's `PATH` variable does not correctly point to the installed packages.

fix Ensure PyIMG4 is installed in your current environment: `python3 -m pip install pyimg4`. If using a virtual environment, activate it first. For system-wide issues on Linux, ensure `python3-pip` is installed and the 'universe' repository is enabled (`sudo add-apt-repository universe && sudo apt update`).
```
Error: Command 'setup.py install' failed with error code 1 (or similar errors related to `pylzss`, `apple-compress`, `lzfse` during installation).
```
cause This usually indicates missing build tools (e.g., C compiler) required by binary dependencies or conflicts with platform-specific compression libraries.

fix Ensure development headers and compilers are installed (e.g., `sudo apt install build-essential python3-dev` on Debian/Ubuntu, or Xcode Command Line Tools on macOS). Reinstall `pyimg4` with caching disabled: `pip install --no-cache-dir --upgrade pyimg4`.
```
CLI: `Error: 'NoneType' object has no attribute 'get_data'` when using `pyimg4 [im4m/img4] info`
```
cause This error occurs in older versions of PyIMG4 (prior to v0.8.7) when attempting to display information for IM4M files where some values might be null or malformed, leading to unexpected `None` objects.

fix Upgrade PyIMG4 to the latest version: `pip install --upgrade pyimg4`. This issue was addressed in v0.8.7.

Warnings

breaking Python 3.8 support was dropped in PyIMG4 v0.8.7. Users on Python 3.8 or older will need to upgrade their Python environment or use an older PyIMG4 version.
Fix: Upgrade Python to 3.9 or higher: `pyenv install 3.9` / `conda install python=3.9`.
breaking Compression libraries (apple-compress/lzfse) are no longer optional since v0.8.4. Previous installations that relied on the `[compression]` extra might encounter `RuntimeError` if these dependencies are missing, though `pip` should automatically handle platform-specific installations now.
Fix: Ensure a clean reinstall to pick up new dependencies: `pip install --no-cache-dir --upgrade pyimg4`. If issues persist, manually install: `pip install apple-compress` (macOS) or `pip install lzfse` (other OS).
breaking Class names were refactored in v0.7. `pyimg4.ManifestProperty` was renamed to `pyimg4._Property`, and `pyimg4.ManifestImageData` was renamed to `pyimg4._PropertyGroup`. New classes (`pyimg4.ManifestProperty` and `pyimg4.ManifestImageProperties`) now subclass these internal names.
Fix: Update imports and code to use the new class names for manifest properties and image data.
gotcha The `asn1` dependency was pinned to `<3.0.0` in v0.8.8. If you have `asn1` version 3.0.0 or higher installed, it might cause dependency conflicts or `PyIMG4` to fail installation/operation.
Fix: Downgrade `asn1`: `pip install 'asn1<3.0.0'`. Consider using a virtual environment to manage dependencies.

Install

pip install pyimg4 Standard Installation

Imports

IMG4
wrong:
```
import IMG4
```
correct:
```
from pyimg4 import IMG4
```
Classes like IMG4, IM4M, IM4P are directly imported from the pyimg4 package.
IM4M
```
from pyimg4 import IM4M
```
IM4P
```
from pyimg4 import IM4P
```

Quickstart

This quickstart demonstrates how to parse an Image4 file, display its contents, and extract the IM4P payload data using PyIMG4. It simulates reading a dummy Image4 file for immediate execution.

from pyimg4 import IMG4

# Example: Extracting IM4P payload from an IMG4 file
try:
    # Simulate reading an IMG4 file (replace 'path/to/myfile.img4' with actual path)
    # For demonstration, we create a dummy file. In a real scenario, this would be `open('myfile.img4', 'rb')`
    dummy_img4_data = b'IMG4\x00\x00\x00\x01\x00\x00\x00\x00IM4P\x00\x00\x00\x01\x00\x00\x00\x00ABCD\x00\x00\x00\x08\x00\x00\x00\x00IM4M\x00\x00\x00\x01\x00\x00\x00\x00MNFT\x00\x00\x00\x04DATA'
    
    # Open the IMG4 file (or use dummy data as shown)
    i = IMG4(dummy_img4_data)

    print("IMG4 file content:")
    i.show() # Display the structure of the IMG4 object

    # Extract and print the IM4P payload data
    if i.IM4P and i.IM4P.DATA:
        print("\nExtracted IM4P Payload Data (first 100 bytes):")
        print(i.IM4P.DATA[:100])
    else:
        print("No IM4P payload data found.")

except Exception as e:
    print(f"An error occurred: {e}")

view raw JSON →