{"id":5177,"library":"delocate","title":"Delocate macOS Dynamic Library Bundler","description":"delocate is a Python library and command-line tool designed to move macOS dynamic libraries into Python packages, particularly for wheels. It helps bundle native dependencies directly into a wheel, making it self-contained and distributable across macOS systems. Currently at version 0.13.0, it maintains an active release cadence with regular updates.","status":"active","version":"0.13.0","language":"en","source_language":"en","source_url":"https://github.com/matthew-brett/delocate","tags":["macos","packaging","wheel","build","dependency management","binary","dylibs"],"install":[{"cmd":"pip install delocate","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core dependency for parsing and manipulating macOS Mach-O files.","package":"machotools","optional":false},{"reason":"Used for parsing and working with Python package versions.","package":"packaging","optional":false},{"reason":"Standard Python packaging tools, often used in conjunction with delocate's operations.","package":"setuptools","optional":false}],"imports":[{"note":"Primary function for processing a single wheel file programmatically.","symbol":"delocate_wheel","correct":"from delocate.delocating import delocate_wheel"},{"note":"Programmatic equivalent for merging library dependencies from multiple trees (low-level, often handled by delocate-merge).","symbol":"fuse_trees","correct":"from delocate.fuse import fuse_trees"},{"note":"Programmatic function for merging two wheel files, replacing the deprecated `delocate.fuse` command-line tool.","symbol":"merge_wheels","correct":"from delocate.merge import merge_wheels"}],"quickstart":{"code":"import os\nimport shutil\nfrom pathlib import Path\nfrom delocate.delocating import delocate_wheel\n\n# This quickstart demonstrates how to programmatically call delocate_wheel.\n# For a real use case, 'input_wheel_path' would be a path to a built .whl file\n# that contains macOS dynamic libraries.\n\n# Define paths for a dummy scenario\noutput_dir = Path(\"delocated_wheels_output\")\ndummy_wheel_name = \"my_package-1.0-py3-none-any.whl\" # Placeholder\ninput_wheel_path = Path(dummy_wheel_name) # This path needs to exist for real operation\noutput_wheel_path = output_dir / dummy_wheel_name\n\n# Ensure output directory exists for illustration, and remove if run multiple times\nif output_dir.exists():\n    shutil.rmtree(output_dir)\noutput_dir.mkdir(parents=True, exist_ok=True)\n\nprint(f\"Attempting to delocate a dummy wheel '{input_wheel_path}'\\n\" \n      f\"and save processed output to '{output_wheel_path}'.\\n\"\n      f\"NOTE: This will fail unless '{input_wheel_path}' is a real .whl file.\")\n\ntry:\n    # In a real scenario, input_wheel_path would point to an existing .whl.\n    # delocate_wheel will attempt to read, modify, and write the wheel.\n    # Using a non-existent path here illustrates the function call pattern.\n    delocate_wheel(\n        str(input_wheel_path),\n        str(output_wheel_path),\n        lib_sdir='.dylibs', # Default is 'delocate'\n        check_archs=True,\n        require_archs=None,\n        check_libs=True,\n        always_copy_libs=False,\n        signed_libs=False,\n        repair_libs=True,\n        fix_rpaths=True, # Default to True since 0.12.0\n        strip_executables=True,\n        ignore_missing_libraries=False,\n        verbose=1\n    )\n    print(f\"Successfully called delocate_wheel (output to: {output_wheel_path}).\")\nexcept Exception as e:\n    # delocate_wheel will raise an error if input_wheel_path does not exist\n    print(f\"Caught expected error (input wheel not found for dummy example): {type(e).__name__}: {e}\")\n\n# Cleanup dummy output directory\nif output_dir.exists():\n    shutil.rmtree(output_dir)","lang":"python","description":"This quickstart demonstrates the programmatic use of `delocate_wheel` to process a wheel file. It sets up dummy paths and illustrates the function signature. Note that for actual operation, `input_wheel_path` must point to an existing .whl file containing macOS dynamic libraries."},"warnings":[{"fix":"Migrate any scripts or workflows using `delocate-fuse` to `delocate-merge`.","message":"The command-line tool `delocate-fuse` was removed in version 0.12.0. Its functionality for merging wheels is now provided by the `delocate-merge` command.","severity":"breaking","affected_versions":">=0.12.0"},{"fix":"If the previous behavior (no automatic RPATH sanitization) is required, explicitly use the `--no-sanitize-rpaths` flag when invoking `delocate-wheel` or set `fix_rpaths=False` when calling `delocate_wheel`.","message":"Starting with version 0.12.0, the `--sanitize-rpaths` behavior is enabled by default for `delocate-wheel` and `delocate_wheel`. This means RPATHs in bundled binaries will be automatically sanitized, which might alter the resulting wheel compared to previous versions.","severity":"breaking","affected_versions":">=0.12.0"},{"fix":"Update exception handling blocks to catch `FileNotFoundError` instead of `ValueError` for scenarios involving missing patch files when interacting with `patch_wheel` or debugging `delocate_wheel`.","message":"The `patch_wheel` function (internally used by `delocate_wheel` and `delocate-wheel`) now raises `FileNotFoundError` instead of `ValueError` when required patch files are missing. This change impacts error handling for missing dependencies within the wheel.","severity":"breaking","affected_versions":">=0.13.0"},{"fix":"Avoid using these deprecated functions in new code. For multi-architecture aware operations or similar functionality, consult the latest `delocate` documentation for alternative approaches.","message":"Functions `get_rpaths`, `get_install_id`, and `unique_by_index` are deprecated as of version 0.13.0. These functions are being phased out, particularly due to their lack of comprehensive multi-architecture support.","severity":"deprecated","affected_versions":">=0.13.0"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}