delvewheel 0.0.23

Self-contained wheels for Windows

delvewheel

delvewheel is a command-line tool for creating Python wheel packages for Windows that have DLL dependencies that may not be present on the target system. It is functionally similar to auditwheel (for Linux) and delocate (for Mac OS).

Suppose that you have built a Python wheel for Windows containing an extension module, but the wheel depends on DLLs that are present in the build environment but may not be present on the end user's machine. This tool determines which DLLs a wheel depends on (aside from system libraries) and copies those DLLs into the wheel.

Installation

delvewheel can be installed using pip.

pip install delvewheel

You can also install from the source code by opening a command-line shell at the repository root and running

pip install .

Python 3.6+ is required. Although the wheels that delvewheel repairs are for Windows, delvewheel itself can be run on other platforms.

Usage

delvewheel show: show external DLLs that the wheel depends on

delvewheel repair: copy external DLL dependencies into the wheel and patch the wheel so that these libraries are loaded at runtime

delvewheel needed: list the direct DLL dependencies of a single executable

delvewheel searches for the location of DLL dependencies in the following order.

1. The PATH environment variable.
2. The Visual C++ 14.x runtime redistributable directory, if it exists.

To specify an additional directory to search for DLLs, add the location of the DLL to the PATH environment variable or use the --add-path option.

For a summary of additional command-line options, use the -h option (delvewheel -h, delvewheel show -h, delvewheel repair -h, delvewheel needed -h).

Additional Options

The path separator to use in the following options is ';' on Windows and ':' on Unix-like platforms.

delvewheel show

• --add-path: additional path(s) to search for DLLs, path-separator-delimited. These paths are searched before those in the PATH environment variable.
• --add-dll: name(s) of additional DLL(s) to vendor into the wheel, path-separator-delimited. We do not automatically search for dependencies of these DLLs unless another included DLL depends on them.
• --no-dll: name(s) of DLL(s) to specifically exclude from the wheel, path-separator-delimited. Dependencies of these DLLs are also automatically excluded if no other included DLL depends on them.
• --ignore-in-wheel: don't search for or vendor in DLLs that are already in the wheel. We still search for and vendor in dependencies of these DLLs if they are not in the wheel. This flag is meant for simpler integration with other DLL bundling tools/techniques but is not a catch-all. If you use this flag, it is your responsibility to ensure that the DLLs that are already in the wheel are loaded correctly.
• -v: verbosity
  • -v: level 1, some diagnostic information
  • -vv: level 2, include warnings from pefile
• --extract-dir: directory to store extracted contents of wheel for debug use (default is a temp directory)

delvewheel repair

• --add-path: additional path(s) to search for DLLs, path-separator-delimited. These paths are searched before those in the PATH environment variable.
• --add-dll: name(s) of additional DLL(s) to vendor into the wheel, path-separator-delimited. We do not automatically search for or vendor in dependencies of these DLLs unless another included DLL depends on them. We do not mangle the names of these DLLs or their direct dependencies.
• --no-dll: name(s) of DLL(s) to specifically exclude from the wheel, path-separator-delimited. Dependencies of these DLLs are also automatically excluded if no other included DLL depends on them.
• --ignore-in-wheel: don't search for or vendor in DLLs that are already in the wheel. Don't mangle the names of these DLLs or their direct dependencies. We still search for and vendor in dependencies of these DLLs if they are not in the wheel. This flag is meant for simpler integration with other DLL bundling tools/techniques but is not a catch-all. If you use this flag, it is your responsibility to ensure that the DLLs that are already in the wheel are loaded correctly.
• -v: verbosity
  • -v: level 1, some diagnostic information
  • -vv: level 2, include warnings from pefile
• --extract-dir: directory to store extracted contents of wheel for debug use (default is a temp directory)
• -w,--wheel-dir: directory to write the repaired wheel (default is wheelhouse relative to current working directory)
• --no-mangle: name(s) of DLL(s) not to mangle, path-separator-delimited; leave blank to avoid mangling all DLLs
• -L,--lib-sdir: subdirectory suffix in package to store vendored DLLs (default .libs)

Limitations

• delvewheel reads DLL file headers to determine which libraries a wheel depends on. DLLs that are loaded at runtime using ctypes/cffi (from Python) or LoadLibrary (from C/C++) will be missed. You can, however, specify additional DLLs to vendor into the wheel using the --add-dll option. If you elect to do this, it is your responsibility to ensure that the DLL is found at load time.
• Wheels created using delvewheel are not guaranteed to work on systems older than Windows 7. If you intend to create a wheel for an old Windows system, you should test the resultant wheel thoroughly. If it turns out that getting the wheel to work on an older system simply requires an extra DLL, you can use the --add-dll flag to vendor additional DLLs into the wheel.
• To avoid DLL hell, we mangle the file names of most DLLs that are vendored into the wheel. This way, a Python process that tries loading a vendored DLL does not end up using a different DLL with the same name. Due to a limitation in the machomachomangler dependency, delvewheel is unable to name-mangle DLLs containing extra data at the end of the binary. If your DLL was created with MinGW, you can use the strip utility to remove the extra data. Otherwise, use the --no-mangle flag.
• Windows ARM wheels are not yet supported.
• delvewheel cannot repair a wheel that contains extension modules targeting more than one CPU architecture (e.g. both 32-bit x86 and 64-bit x86). You should create a separate wheel for each CPU architecture and repair each individually.