mhammond/pywin32

pywin32

This is the readme for the Python for Win32 (pywin32) extensions, which provides access to many of the Windows APIs from Python, including COM support.

See CHANGES.md for recent notable changes.

adodbapi's documentation can be found in: adodbapi/readme.txt

isapi's documentation can be found in: isapi/README.txt

Docs

The docs are a long and sad story, but there's now an online version of the PyWin32.chm helpfile (thanks @ofek!). Lots of that is very old, but some is auto-generated and current. Would love help untangling the docs!

You can get type hints, signatures and annotations from types-pywin32.

Support

Feel free to open issues for all bugs (or suspected bugs) in pywin32. pull-requests for all bugs or features are also welcome.

However, please do not open GitHub issues for general support requests, or for problems or questions using the modules in this package.
For pywin32 support requests, please start a discussion under the Q&A category. All non bug related issues will be converted into a discussion anyhow.
The python-win32 mailing list is still available for general Python on Windows help requests.

Type stubs currently live in typeshed. Any issue or request related to static type-checking and IntelliSense should be raised there.

Binaries

Binary releases are no longer supported.

Build 306 was the last with .exe installers. You really shouldn't use them, but if you really need them, find them here

Installing via PIP

You should install pywin32 via pip - eg,

python -m pip install --upgrade pywin32

There is a post-install script (see below) which should not be run inside virtual environments; it should only be run in "global" installs.

For unreleased changes, you can download builds made by GitHub actions - choose any "workflow" from the main branch and download its "artifacts"

Free-threaded support

Building via pip with a no-GIL interpreter will create a compatible, but knowingly unsafe, wheel. This should be considered experimental; while knowingly unsafe, no wheels compatible with the free-threaded interpreter will be made available - but you can build them yourself.

See NOGIL.md for the blockers to supplying these artifacts.

Installing globally

Outside of a virtual environment you might want to install COM objects, services, etc. You can do this by executing:

python -m pywin32_postinstall -install

or (shorter but you don't have control over which python environment is used)

pywin32_postinstall -install

If you do this with normal permissions it will be global for your user (a few files will be copied to the root of your Python install and some changes made to HKCU). If you execute this from an elevated process, it will be global for the machine (files will be copied to System32, HKLM will be changed, etc)

Installing for MinGW/MSYS2

Install the package hosted by MINGW-packages (see mingw-w64-python-pywin32), from the MSYS2 shell of your environment:

pacman -S ${MINGW_PACKAGE_PREFIX}-python-pywin32

pywin32 builds from source with MinGW-w64 (GCC or Clang) without any patches, and the MinGW build runs on our CI. Pythonwin (win32ui, win32uiole, dde and Pythonwin.exe) requires MFC, which is only available with MSVC, so it isn't included.

Problems building pywin32 with MinGW should be reported here. Packaging issues (availability, versions, environments) belong in MINGW-packages.

Running as a Windows Service

To run as a service, you probably want to install pywin32 globally from an elevated command prompt - see above.

You also need to ensure Python is installed in a location where the user running the service has access to the installation and is able to load pywintypesXX.dll and pythonXX.dll. In particular, the LocalSystem account typically will not have access to your local %USER% directory structure.

Troubleshooting

If you encounter any problems when upgrading like the following:

The specified procedure could not be found
Entry-point not found

It usually means one of 2 things:

• You've upgraded an install where the post-install script was previously run. So you should run it again:

  python -m pywin32_postinstall -install
  

  or (shorter but you don't have control over which python environment is used)

  pywin32_postinstall -install
  

  This will make some small attempts to cleanup older conflicting installs.

• There are other pywin32 DLLs installed in your system, but in a different location than the new ones. This sometimes happens in environments that come with pywin32 pre-shipped (eg, anaconda?).

  The possible solutions here are:

  • Run the "post_install" script documented above.
  • Otherwise, find and remove all other copies of pywintypesXX.dll and pythoncomXX.dll (where XX is the Python version - eg, "39")

Building from source

Install Visual Studio 2019 (later probably works, but options might be different), follow the instructions in Build environment for the version you install.

Then follow the Build instructions for the build itself (including ARM64 cross-compilation).

Release process

The following steps are performed when making a new release - this is mainly to form a checklist so @mhammond doesn't forget what to do :)

Since build 307 the release process is based on the artifacts created by Github actions.

• Ensure CHANGES.md has everything worth noting. Update the header to reflect the about-to-be released build and date, commit it.

• Update setup.py with the new build number. Update CHANGES.md to have a new heading section for the next unreleased version. (ie, a new, empty "Coming in build XXX, as yet unreleased" section)

• Push these changes to GitHub, wait for the actions to complete, then download the artifacts from that run.

• Upload .whl artifacts to pypi - we do this before pushing the tag because they might be rejected for an invalid README.md. Done via py -3.? -m twine upload dist/*XXX*.whl.

• Create a new git tag for the release.

• Update setup.py with the new build number + ".1" (eg, 123.1), to ensure future test builds aren't mistaken for the real release.

• Make sure everything is pushed to GitHub, including the tag (ie, git push --tags)

• Send mail to python-win32

Versioning

pywin32 uses a simple incremental version numbering scheme. Any increase in the version number may correspond to a breaking interface change. It is recommended that projects using pywin32 pin the dependency to a specific version.

Licenses

pywin32 contains a mix of differently licensed code. The license files in the source tree are the source of truth.¹. So are individual Copyright notices at the top of files. You can also find license information through the License-File Packaging Metadata.