Delvewheel

1.12.0 · active · verified Thu Apr 16

Delvewheel is a utility that creates self-contained Python wheels for Windows by embedding external shared libraries (DLLs) into the wheel. This helps to eliminate common 'DLL not found' errors when deploying Python packages on Windows. The current version is 1.12.0, and it is actively maintained with releases tied to necessary updates for Python versions or dependency handling.

Common errors

```
Error: delvewheel is only supported on Windows.
```
cause Attempting to run `delvewheel` on a non-Windows operating system (e.g., Linux, macOS).

fix Run `delvewheel` exclusively on a Windows machine. For Linux wheels, `auditwheel` is the equivalent tool.
```
Error: no wheels matching 'my_package-*.whl' found.
```
cause The path or glob pattern provided to `delvewheel repair` does not match any existing wheel files, or the wheel files are in a different directory.

fix Verify that the wheel file(s) exist at the specified path and that the filename pattern is correct. Use `ls` or `dir` to confirm the file's presence and exact name.
```
Error: Could not find MSVC runtime DLLs. Ensure you are using a Python built with MSVC.
```
cause `delvewheel` needs to embed MSVC runtime DLLs from the Python installation but cannot locate them. This typically happens if Python was built with a different compiler (e.g., MinGW) or is not a standard Python.org distribution.

fix Install and use a standard Python distribution for Windows, typically from python.org, which is built with Visual Studio/MSVC. Avoid custom builds or distributions that might not include these runtimes.
```
Failed to find a DLL for 'dependency.dll'.
```
cause During the dependency scan, `delvewheel` could not locate a required shared library (`.dll`) that your package or its dependencies rely on.

fix Ensure `dependency.dll` is available in your system's PATH during the `delvewheel repair` execution. For complex cases, you might need to manually copy the DLL into a location discoverable by `delvewheel` before running the repair, or ensure it's part of the original wheel's build process.

Warnings

breaking Delvewheel is exclusively for Windows wheels. Attempting to use it on Linux or macOS will result in an error, and it has no functionality for these operating systems.
Fix: Ensure you are running delvewheel on a Windows operating system. For Linux wheels, consider `auditwheel`.
gotcha Wheels repaired by delvewheel may still require specific versions of the Visual C++ Redistributables (VCRedist) on the target machine if the original DLLs depend on external VCRedist versions not bundled with Python. Delvewheel primarily embeds MSVC runtime libraries from the Python installation it's run with.
Fix: Test your repaired wheels on a clean Windows environment. If VCRedist errors occur, ensure the target machine has the necessary VCRedist installed, or investigate if the original DLLs can be linked against a different runtime.
gotcha Delvewheel might not find or correctly embed all custom or deeply embedded DLLs, especially those not in standard system paths, relative paths, or those loaded dynamically at runtime in complex ways. It relies on dependency scanning.
Fix: If a DLL is consistently missed, try to make it discoverable by adding its directory to the system PATH temporarily during the `delvewheel repair` process or by explicitly specifying its location if the original build process allows.
gotcha Ensure the Python interpreter running `delvewheel` is compatible with the wheel's target Python version and architecture (e.g., Python 3.9 64-bit for a `cp39-win_amd64` wheel). Incompatibilities can lead to issues with embedding MSVC runtimes or incorrect dependency resolution.
Fix: Always use a Python environment matching the wheel's target when running `delvewheel repair`. For example, use a Python 3.9 environment to repair Python 3.9 wheels.

Install

pip install delvewheel Install stable version

Imports

main
```
from delvewheel.delvewheel import main
```
Delvewheel is primarily a command-line utility. While `main` can be imported and called programmatically, common usage is via `python -m delvewheel` or the `delvewheel` executable.

Quickstart

To use delvewheel, you typically invoke it from the command line using `python -m delvewheel repair` followed by the path to your wheel file(s). It will create a new, repaired wheel in the same directory or a specified output directory.

# Assume 'my_package-1.0-cp39-cp39-win_amd64.whl' is a wheel file to be repaired
# Run delvewheel from your terminal or command prompt

# Basic repair, will attempt to find and embed DLLs
python -m delvewheel repair my_package-1.0-cp39-cp39-win_amd64.whl

# Repair with custom output directory
python -m delvewheel repair --wheel-dir ./repaired_wheels my_package-1.0-cp39-cp39-win_amd64.whl

view raw JSON →