{"id":2989,"library":"macholib","title":"Mach-O header analysis and editing","description":"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.","status":"active","version":"1.16.4","language":"en","source_language":"en","source_url":"https://github.com/ronaldoussoren/macholib","tags":["macOS","Mach-O","executables","dylib","linking","introspection","binary analysis"],"install":[{"cmd":"pip install macholib","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"While 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.","package":"altgraph","optional":true}],"imports":[{"note":"This is the primary class for loading and interacting with Mach-O files.","symbol":"MachO","correct":"from macholib.MachO import MachO"},{"note":"Provides functions for dynamic linker (dyld) emulation, useful for resolving library paths.","symbol":"dyld","correct":"from macholib import dyld"},{"note":"Utilities for handling macOS framework paths.","symbol":"framework","correct":"from macholib import framework"},{"note":"General utility functions.","symbol":"util","correct":"from macholib import util"}],"quickstart":{"code":"import os\nfrom macholib.MachO import MachO\nfrom macholib import dyld\n\ndef get_macho_dependencies(filepath):\n    try:\n        macho = MachO(filepath)\n        print(f\"Analyzing: {filepath}\")\n        for header in macho.headers:\n            print(f\"  Architecture: {header.architecture()}\")\n            for idx, name, other in header.walk_libraries():\n                resolved_name = dyld.dyld_find(name, executable_path=filepath)\n                print(f\"    Depends on: {name} (Resolved: {resolved_name})\")\n    except Exception as e:\n        print(f\"Error processing {filepath}: {e}\")\n\n# Example usage with a common macOS binary\n# Ensure the file exists, e.g., '/usr/bin/ls'\nsystem_binary = os.environ.get('MACHO_BINARY_PATH', '/usr/bin/ls')\nif os.path.exists(system_binary):\n    get_macho_dependencies(system_binary)\nelse:\n    print(f\"Skipping quickstart: {system_binary} not found. Set MACHO_BINARY_PATH to a valid Mach-O file.\")","lang":"python","description":"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."},"warnings":[{"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`.","message":"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.","severity":"breaking","affected_versions":">=1.4"},{"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.","message":"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.","severity":"deprecated","affected_versions":">=1.4"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.16"},{"fix":"Avoid using `macholib.macho_dump.ARCH_MAP`. Rely on official APIs or direct Mach-O header parsing for architecture information.","message":"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.","severity":"deprecated","affected_versions":">=1.4.2"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}