macholib

library1.16.4pypypi✓ verified 24d ago

macholib is a Python library used for analyzing and editing Mach-O headers, the executable format employed by macOS. It functions primarily as a dependency analysis tool, capable of rewriting dylib references within Mach-O headers to be @executable_path relative. The library is pure Python, platform, and endian-independent, currently at version 1.16.4, with active development and regular releases.

serialization devops

pip install macholib

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · MACHOLIB

macholib

serializationpythonv1.16.4

Install

1.7s avg

Import

15ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.16.4 · 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

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.016s · 18.3MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.7s · import 0.014s · 19MB

16MB installed

● package 16MB

Code

Verified usage

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

MachO

✓ from macholib.MachO import MachO

This is the primary class for loading and interacting with Mach-O files.

dyld

✓ from macholib import dyld

Provides functions for dynamic linker (dyld) emulation, useful for resolving library paths.

framework

✓ from macholib import framework

Utilities for handling macOS framework paths.

util

✓ from macholib import util

General utility functions.

This quickstart demonstrates how to load a Mach-O binary using `macholib.MachO` and then iterate through its linked libraries, attempting to resolve their paths using `macholib.dyld.dyld_find`. It prints the architecture and dependencies of a specified Mach-O file.

import os from macholib.MachO import MachO from macholib import dyld def get_macho_dependencies(filepath): try: macho = MachO(filepath) print(f"Analyzing: {filepath}") for header in macho.headers: print(f" Architecture: {header.architecture()}") for idx, name, other in header.walk_libraries(): resolved_name = dyld.dyld_find(name, executable_path=filepath) print(f" Depends on: {name} (Resolved: {resolved_name})") except Exception as e: print(f"Error processing {filepath}: {e}") # Example usage with a common macOS binary # Ensure the file exists, e.g., '/usr/bin/ls' system_binary = os.environ.get('MACHO_BINARY_PATH', '/usr/bin/ls') if os.path.exists(system_binary): get_macho_dependencies(system_binary) else: print(f"Skipping quickstart: {system_binary} not found. Set MACHO_BINARY_PATH to a valid Mach-O file.")

Debug

Known issues

breakingThe standalone command-line tools `macho_find`, `macho_dump`, and `macho_standalone` were deprecated in version 1.4. They have been replaced by the module-execution interface: `python -m macholib find`, `python -m macholib dump`, and `python -m macholib standalone` respectively.

fix

Migrate usage of `macho_find`, `macho_dump`, `macho_standalone` to `python -m macholib <subcommand>`. For example, replace `macho_dump /path/to/binary` with `python -m macholib dump /path/to/binary`.

affects: >=1.4

deprecatedIn version 1.4, private functionality (identified by names starting with an underscore) within modules was renamed, and basic packable types in `macholib.ptypes` were renamed to better represent corresponding C types. Old `ptypes` names are deprecated and will be removed in future releases.

fix

Review code for reliance on internal, underscored functions or old `macholib.ptypes` names. Update to the new public API or C-type representative names as per documentation to ensure future compatibility.

affects: >=1.4

gotchaVersion 1.16 introduced the `allow_unknown_load_commands` option to `MachO` and `macholib.MachOHeader`. If set to `False` (which might be the default in some contexts or previous versions' implicit behavior), parsing a file with unknown load commands will raise an error. If `True`, unknown commands are ignored. This can change error-handling behavior for malformed or newer Mach-O files.

fix

When instantiating `MachO` or `MachOHeader`, explicitly set `allow_unknown_load_commands=True` if you want to gracefully handle files with unrecognized load commands without raising an error. Be aware of the implications for parsing validity.

affects: >=1.16

deprecatedThe mapping `macholib.macho_dump.ARCH_MAP` was undocumented and no longer used internally by `macholib` as of version 1.4.2, and was scheduled for removal in a subsequent release.

fix

Avoid using `macholib.macho_dump.ARCH_MAP`. Rely on official APIs or direct Mach-O header parsing for architecture information.

affects: >=1.4.2

Errors

Common errors & fixes

ImportError: No module named macholib.MachO

This error occurs either because the `macholib` package is not installed, or because the `MachO` class (or other submodules) is not explicitly imported into the current namespace after a general `import macholib` statement.

fix

First, ensure `macholib` is installed: `pip install macholib`. If it is installed, specifically import the `MachO` class: `from macholib import MachO` or `from macholib.MachO import MachO`. If only `import macholib` is used, access the class via `macholib.MachO`.

ValueError: Unknown Mach-O header: 0x...

This `ValueError` typically indicates that `macholib` is attempting to parse a file that is not a valid Mach-O executable, or it's a Mach-O file with an unexpected or unsupported header format or load command, possibly due to newer macOS versions or file corruption.

fix

Verify that the file you are attempting to parse is a valid Mach-O executable. If the file is valid, consider updating `macholib` to the latest version (`pip install --upgrade macholib`), as newer versions may include support for recently introduced Mach-O formats or load commands.

OSError: seek to offset N is outside window

This `OSError` suggests an issue with file I/O where `macholib` tries to seek to an offset within the Mach-O file that is beyond the file's boundaries or the boundaries of a defined segment it is trying to read, often indicating a malformed or corrupted Mach-O file.

fix

Ensure the Mach-O file being processed is intact and not corrupted. If the file is known to be valid, this might point to a specific edge case or bug within `macholib`'s parsing logic, in which case upgrading the library (`pip install --upgrade macholib`) or reporting the issue to the `macholib` project could be necessary.

Upgrade

Version history

1.16.4latest on PyPI · released Nov 22, 2025

Audit

Dependencies

altgraphoptionalWhile not a hard dependency in macholib's setup.py, many common use cases (e.g., dependency graphing, tools like py2app) and even basic examples often implicitly rely on `altgraph` for full functionality related to graph manipulation and dependency resolution.

Agent activity

7 hits · last 30 days

node

Resources

githubhttp://github.com/ronaldoussoren/macholib ↗

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

docshttps://macholib.readthedocs.io/en/latest/ ↗