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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.174s · 21.4MB
glibcpy 3.10–3.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
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.
fixCorrect 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.
fixUpdate 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.
fixFirst, 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.
fixInvestigate 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.