Registry / devops / delocate

delocate

JSON →
library0.13.0pypypi✓ verified 23d ago

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.

pip install delocate
INSTALL
IMPORT
SIG · DELOCATE
D
delocate
devopspythonv0.13.0
Install
1.9s avg
Import
171ms
Disk
20MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.13.0 · 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.103.95 runs
installs and imports cleanly · install 0.0s · import 0.174s · 21.4MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 1.9s · import 0.168s · 22MB
20MB installed
● package 20MB
Code
Verified usage

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

delocate_wheel
from delocate.delocating import delocate_wheel
Primary function for processing a single wheel file programmatically.
fuse_trees
from delocate.fuse import fuse_trees
Programmatic equivalent for merging library dependencies from multiple trees (low-level, often handled by delocate-merge).
merge_wheels
from delocate.merge import merge_wheels
Programmatic function for merging two wheel files, replacing the deprecated `delocate.fuse` command-line tool.

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.

import os import shutil from pathlib import Path from delocate.delocating import delocate_wheel # This quickstart demonstrates how to programmatically call delocate_wheel. # For a real use case, 'input_wheel_path' would be a path to a built .whl file # that contains macOS dynamic libraries. # Define paths for a dummy scenario output_dir = Path("delocated_wheels_output") dummy_wheel_name = "my_package-1.0-py3-none-any.whl" # Placeholder input_wheel_path = Path(dummy_wheel_name) # This path needs to exist for real operation output_wheel_path = output_dir / dummy_wheel_name # Ensure output directory exists for illustration, and remove if run multiple times if output_dir.exists(): shutil.rmtree(output_dir) output_dir.mkdir(parents=True, exist_ok=True) print(f"Attempting to delocate a dummy wheel '{input_wheel_path}'\n" f"and save processed output to '{output_wheel_path}'.\n" f"NOTE: This will fail unless '{input_wheel_path}' is a real .whl file.") try: # In a real scenario, input_wheel_path would point to an existing .whl. # delocate_wheel will attempt to read, modify, and write the wheel. # Using a non-existent path here illustrates the function call pattern. delocate_wheel( str(input_wheel_path), str(output_wheel_path), lib_sdir='.dylibs', # Default is 'delocate' check_archs=True, require_archs=None, check_libs=True, always_copy_libs=False, signed_libs=False, repair_libs=True, fix_rpaths=True, # Default to True since 0.12.0 strip_executables=True, ignore_missing_libraries=False, verbose=1 ) print(f"Successfully called delocate_wheel (output to: {output_wheel_path}).") except Exception as e: # delocate_wheel will raise an error if input_wheel_path does not exist print(f"Caught expected error (input wheel not found for dummy example): {type(e).__name__}: {e}") # Cleanup dummy output directory if output_dir.exists(): shutil.rmtree(output_dir)
delocate --version
Debug
Known issues
breakingThe 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.
fix
Migrate any scripts or workflows using `delocate-fuse` to `delocate-merge`.
affects: >=0.12.0
breakingStarting 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.
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`.
affects: >=0.12.0
breakingThe `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.
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`.
affects: >=0.13.0
deprecatedFunctions `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.
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.
affects: >=0.13.0
Errors
Common errors & fixes
DelocationError: library "<long temporary path>/wheel/libme.dylib" does not exist.
This error typically occurs when a dynamic library within your wheel specifies a dependency using a relative path that `delocate` cannot resolve, often because the original library's `install_name_id` was not an absolute path during its own build.
fix
Correct the build process of your native libraries to ensure they have absolute `install_name_id` values (e.g., `/path/to/libme.dylib`). For CMake projects, consider using `CMAKE_INSTALL_NAME_DIR` to set appropriate install names.
delocate-fuse: command not found
The `delocate-fuse` command-line tool was removed in `delocate` version 0.12.0 and later, replaced by `delocate-merge` for combining wheels.
fix
Update your scripts and workflows to use the `delocate-merge` command instead of `delocate-fuse`. If the deprecated `delocate-fuse` functionality is strictly required, you can pin your `delocate` version to `0.11.0` or earlier.
delocate-wheel: command not found
This error indicates that the `delocate-wheel` executable is not found in your system's PATH environment variable, or the `delocate` package is not installed in your active Python environment.
fix
First, ensure `delocate` is installed using `pip install delocate`. If it is installed, verify that the directory containing the `delocate` command-line tools (e.g., typically `~/.local/bin` or within your virtual environment's `bin` directory) is included in your system's PATH.
DelocationError: Already planning to copy library with same basename as: xxxx
`delocate` encountered multiple dynamic libraries within the wheel that share the same base filename, leading to a conflict when attempting to copy and relocate them into the package.
fix
Investigate your wheel's dependencies to identify why multiple libraries with identical basenames are being included. You may need to adjust your build configuration to ensure unique naming for native libraries or to prevent redundant dependencies from being bundled.
Upgrade
Version history
0.13.0latest on PyPI · released Jan 30, 2025
Audit
Dependencies
machotoolsrequiredCore dependency for parsing and manipulating macOS Mach-O files.
packagingrequiredUsed for parsing and working with Python package versions.
setuptoolsrequiredStandard Python packaging tools, often used in conjunction with delocate's operations.
Agent activity
14 hits · last 30 days
node
12
Resources
delocate — pip install delocate · libregistry