pyimg4

library0.8.8pypypi✓ verified 89d ago

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.

serialization

pip install pyimg4

github ↗package ↗

INSTALL

IMPORT

SIG · PYIMG4

pyimg4

serializationpythonv0.8.8

Install

2.5s avg

Import

149ms

Disk

28MB

Pass rate

8/ 10

Env Coverage8 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.8.8 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✓ —

✓ 2.38s

py 3.11

✓ —

✓ 2.43s

py 3.12

✓ —

✓ 2.25s

py 3.13

✕ build_error

py 3.9

✓ —

✓ 2.78s

28MB installed

● package 28MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

IMG4

✓ from pyimg4 import IMG4

✗ import IMG4

Classes like IMG4, IM4M, IM4P are directly imported from the pyimg4 package.

IM4M

✓ from pyimg4 import IM4M

IM4P

✓ from pyimg4 import IM4P

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}")

pyimg4 --version

Debug

Known issues

breakingPython 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`.

affects: >=0.8.7

breakingCompression 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).

affects: >=0.8.4

breakingClass 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.

affects: >=0.7

gotchaThe `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.

affects: >=0.8.8

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'pyimg4' (or 'pyimg4 is not installed')

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).

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`

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.

Upgrade

Version history

0.8.8latest on PyPI · released Apr 1, 2025

Audit

Dependencies

asn1requiredCore dependency for ASN.1 parsing within Image4 format.

scapyrequiredCore dependency for packet manipulation and ASN.1 handling.

apple-compressrequiredRequired for LZFSE compression/decompression on macOS (*OS) systems. Automatically installed by pip if on macOS.

lzfserequiredRequired for LZFSE compression/decompression on non-macOS systems. Automatically installed by pip if not on macOS.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/m1stadev/PyIMG4 ↗

packagehttps://pypi.org/project/pyimg4/ ↗