Package: delvewheel
delvewheeldelvewheelis a command-line tool for creating self-contained Python wheel packages for Windows that have DLL dependencies that may not be present on the target system. It is functionally similar toauditwheel(for Linux) anddelocate(for macOS).Suppose that you have built a Python wheel for Windows containing an extension module, and 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. This tool also takes extra steps to avoidDLL helland to ensure that the DLLs are properly loaded at runtime.Installationdelvewheelcan be installed using pip.pipinstalldelvewheelYou can also install from the source code by opening a command-line shell at the repository root and runningpipinstall.Supported Platformsdelvewheelcan be run using Python 3.7+ on any platform.delvewheelcan repair wheels targeting Python 2.6+ forwin32,win_amd64, orwin_arm64.The environment used to rundelvewheeldoesnotneed to match the target environment of the wheel being repaired. For example, you can rundelvewheelusing 32-bit Python 3.7 to repair a wheel for 64-bit Python 2.6. You can even rundelvewheelwith PyPy3.6 on 32-bit x86 Linux to repair a wheel whose target environment is CPython 3.11 on Windows arm64.Usagedelvewheel show: show external DLLs that the wheel depends ondelvewheel repair: copy external DLL dependencies into the wheel and patch the wheel so that these libraries are loaded at runtimedelvewheel needed: list the direct DLL dependencies of a single executabledelvewheeluses thePATHenvironment variable to search for DLL dependencies. To specify an additional directory to search for DLLs, add the location of the DLL to thePATHenvironment variable or use the--add-pathoption.For a summary of additional command-line options, use the-hoption (delvewheel -h,delvewheel show -h,delvewheel repair -h,delvewheel needed -h).Additional OptionsThe 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 thePATHenvironment 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. If you use this option, it is your responsibility to ensure that the additional DLL is found at load time.--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 frompefile--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 thePATHenvironment 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. If you use this option, it is your responsibility to ensure that the additional DLL is found at load time.--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 frompefile--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 iswheelhouserelative to current working directory)--no-mangle: name(s) of DLL(s) not to mangle, path-separator-delimited--no-mangle-all: don't mangle any DLL names--strip: strip DLLs that contain an overlay when name-mangling. The GNUstriputility must be present inPATH.-L,--lib-sdir: subdirectory suffix to store vendored DLLs (default.libs). For example, if your wheel is namedmywheel-0.0.1-cp310-cp310-win_amd64.whl, then the vendored DLLs are stored inmywheel.libsby default. If your wheel contains a top-level extension module that is not in any package, then this setting is ignored, and vendored DLLs are instead placed directly intosite-packageswhen the wheel is installed.--namespace-pkg: namespace packages, specified in case-sensitive dot notation and delimited by the path separator. Normally, we patch or create__init__.pyin each top-level package to add the vendored DLL location to the DLL search path at runtime. If you have a top-level namespace package that requires__init__.pyto be absent or unmodified, then this technique can cause problems. This option tellsdelvewheelto use an alternate strategy that does not create or modify__init__.pyat the root of the given namespace package(s). For example,--namespace-pkg package1declarespackage1as a namespace package.On Windows,--namespace-pkg package1.package2;package3declarespackage1,package1\package2, andpackage3as namespace packages.--include-symbols: include.pdbsymbol files with the vendored DLLs. To be included, a symbol file must be in the same directory as the DLL and have the same filename before the extension, e.g.example.dllandexample.pdb.Limitationsdelvewheelreads DLL file headers to determine which libraries a wheel depends on. DLLs that are loaded at runtime usingctypes/cffi(from Python) orLoadLibrary(from C/C++) will be missed. You can, however, specify additional DLLs to vendor into the wheel using the--add-dlloption. If you elect to do this, it is your responsibility to ensure that the additional DLL is found at load time.Wheels created usingdelvewheelare not guaranteed to work on systems older than Windows 7 SP1. We avoid vendoring system libraries that are provided by Windows 7 SP1 or later. If you intend to create a wheel for an older Windows system that requires an extra DLL, use the--add-dllflag 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 how name-mangling is performed,delvewheelis unable to name-mangle DLLs whose dependents contain insufficient internal padding to fit the mangled names and contain an overlay at the end of the binary. An exception will be raised if such a DLL is encountered. Commonly, the overlay consists of symbols that can be safely removed using the GNUstriputility, although there exist situations where the data must be present for the DLL to function properly. To remove the overlay, executestrip -s EXAMPLE.dllor use the--stripflag. To keep the overlay and skip name mangling, use the--no-mangleor--no-mangle-allflag.Any DLL containing an Authenticode signature will have its signature cleared if its dependencies are name-mangled.delvewheelcannot repair a wheel that contains extension modules targeting more than one CPU architecture (e.g. bothwin32andwin_amd64). You should create a separate wheel for each CPU architecture and repair each individually.If your project has adelay-load DLL dependency, you must use a custom delay-load import hook when building the DLL that has the delay-load dependency. This ensures that the directory containing the vendored DLLs is included in the DLL search path when delay-loading. For convenience, we provide a suitable hook for Microsoft Visual C/C++ atdelayload/delayhook.c. Add the file to your C/C++ project when building your DLL.An__init__.pyfile in a top-level package or a.pyfile at the root of a namespace package must be parsable by the version of Python that runsdelvewheel. For instance, you cannot rundelvewheelusing Python 3.9 to repair a wheel containing a top-level package with an__init__.pyfile that uses syntax features introduced in Python 3.10. Aside from this rule, there are no other requirements regarding the relationship between the version of Python that runsdelvewheeland the version(s) of Python that the wheel supports.