delvewheel

By default, delvewheel injects patches into __init__.py files to manage the DLL search path. If you need precise control over where these patches are placed, use the --custom-patch option.

When --custom-patch is enabled, delvewheel will look for lines in your .py files containing the unindented comment # delvewheel: patch and replace those lines with the actual patch code.

To prevent "DLL hell" (where different Python modules require different versions of the same DLL name), delvewheel performs name mangling.

The Process:

1. Hashing: delvewheel computes a hash based on the DLL's contents and the hashes of its direct dependencies.
2. Renaming: The DLL is renamed by appending this hash (e.g., C.dll becomes C-a55e90393a19a36b45c623ef23fe3f4a.dll).
3. Import Table Editing: delvewheel modifies the binary's import directory table so the loader looks for the new, mangled filename instead of the original name.

This ensures that multiple versions of the same DLL can coexist in a single Python process because they have unique filenames.

Because delvewheel relies on reading DLL file headers, it cannot automatically detect DLLs loaded dynamically via ctypes, cffi, LoadLibrary (C/C++/Rust), or libloading (Rust).

To include these, use one of the following strategies:

• Manual Inclusion: Use the --include option to specify additional DLLs to vendor into the wheel.
• Analyze Existing: Include the runtime-loaded DLL in the wheel yourself, then use the --analyze-existing option.

Note: You are responsible for ensuring these DLLs are discoverable at load time.

Use delvewheel repair to make a Python wheel self-contained by copying its external DLL dependencies into the wheel and patching it so they are loaded correctly at runtime. This is useful for distributing wheels to users who may not have the required DLLs installed on their systems.

Basic usage:

delvewheel repair WHEEL

delvewheel uses the PATH environment variable to find DLLs. You can also use the --add-path option to specify additional search directories.

If your project uses delay-load DLL dependencies, you must ensure the directory containing the vendored DLLs is in the search path when they are loaded.

For Microsoft Visual C/C++ projects, delvewheel provides a custom delay-load import hook located at delayload/delayhook.c. You should add this file to your C/C++ project during the build process.

The dll_lists/ directory contains lists of .dll and .drv files found in C:\Windows\System32 and C:\Windows\SysWOW64 for various vanilla Windows installations. To identify the intersection of DLLs present across all lists for a specific architecture, run the generate.py script with the corresponding architecture flag.

Note: Files without an export directory table are excluded from these lists. For Windows arm64, non-arm64 DLLs in C:\Windows\System32 are also excluded.

generate.py x86
generate.py x64
generate.py arm64

You can install delvewheel via pip or from the source code.

To install from PyPI:

pip install delvewheel

To install from source, navigate to the repository root and run:

pip install .

If delvewheel cannot mangle a DLL because the dependent binary contains an overlay (extra data at the end) and lacks sufficient internal padding to fit the new mangled names, an exception will be raised.

Solutions:

1. Remove the overlay (Recommended): Strip debug symbols or extra data using the GNU strip utility or the delvewheel flag:

   strip -s EXAMPLE.dll
   # OR
   delvewheel repair --strip

2. Skip mangling: If the overlay is required for functionality, use the --no-mangle or --no-mangle-all flag to bypass the renaming process.

When using show or repair, you can control how delvewheel finds and selects DLLs using the following mechanisms:

Search Paths

Use --add-path to provide additional directories to search for DLLs. These paths are prepended to the system PATH during execution.

Inclusion and Exclusion

• --include / --add-dll: Forces specific DLLs to be included. Use os.pathsep (e.g., ; on Windows) to provide multiple names.
• --exclude / --no-dll: Forces specific DLLs or patterns (using *) to be excluded.

Note: You cannot force both inclusion and exclusion of the same DLL. If a pattern in --exclude matches a name in --include, an error will be raised.

You can control the amount of output information provided by setting the verbose level in the configuration. The level accepts integer values from 0 to 2.

# Example of setting verbosity (internal configuration structure)
config.verbose = 1