Mach-O header analysis and editing

1.16.4 · active · verified Sat Apr 11

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.

Warnings

breaking The 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`.
deprecated In 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.
gotcha Version 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.
deprecated The 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.

Install

pip install macholib Install latest version

Imports

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.

Quickstart

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

view raw JSON →