pywin32 (Python for Windows Extensions)

311 verified Tue May 12 auth: no python install: stale quickstart: stale

pywin32 is an open-source Python library that provides extensive access to many Windows APIs and the Component Object Model (COM). It enables Python scripts to automate Windows applications like Excel and Outlook, interact with system services, manage the clipboard, and perform various other Windows-specific operations. The current version is 311, and the project maintains a frequent release cadence, offering incremental improvements and bug fixes.

pip install pywin32 --upgrade

Common errors

error ModuleNotFoundError: No module named 'win32api' ↓

cause The pywin32 library is not installed in the current Python environment, or its post-installation scripts did not run successfully.

fix

pip install pywin32

error pywintypes.com_error: (-2147221005, 'Invalid class string', None, None) ↓

cause The ProgID (e.g., 'Excel.Application', 'Outlook.Application') passed to `win32com.client.Dispatch` is incorrect, or the corresponding COM object/application is not installed or registered on the system.

fix

Verify the correct ProgID for the desired application and ensure the application is installed and correctly registered on the system.

error AttributeError: <COM object win32com.client.Dispatch of type <unknown>>.Workbooks ↓

cause The COM object you are trying to access does not have the specified attribute or method, or the object is not of the expected type (e.g., trying to access `Workbooks` on a `Workbook` object instead of an `Application` object).

fix

Confirm the correct object hierarchy and ensure you are calling the method/property on the correct COM object instance (e.g., excel_app.Workbooks vs workbook_obj.Sheets).

error TypeError: Argument 'hwndParent' must be an integer ↓

cause An argument passed to a `win32api` or `win32gui` function is of an incorrect Python type (e.g., a string instead of an integer, or an object where a primitive type is expected).

fix

Convert the argument to the expected type, typically an integer (int()), a specific pywin32 constant, or None for null pointers.

error python -m pywin32_postinstall ↓

cause This command is essential after `pip install pywin32` to properly register COM components and generate necessary stub files, but it is often forgotten or run incorrectly, leading to other errors when using `win32com`.

fix

Run python -m pywin32_postinstall -install from an administrator command prompt to ensure all pywin32 components are correctly registered.

Warnings

breaking Binary .exe installers for pywin32 have been deprecated since build 306. Installation should now be performed using pip. ↓

fix Always use `pip install pywin32` or `python -m pip install pywin32` for installation instead of .exe files.

gotcha The `pywin32_postinstall.py` script (located in your Python Scripts directory) is crucial for some functionalities, especially for global installations or when running Windows services, but it should generally NOT be run inside virtual environments. It may require elevated administrator privileges. ↓

fix If experiencing 'module not found' or service-related issues, run `python -m pywin32_postinstall -install` from an elevated (administrator) command prompt, but only in your global Python environment, not in a virtual environment.

gotcha It is critical to match the 'bittedness' (32-bit or 64-bit) of `pywin32` with your Python interpreter's architecture. Installing a 64-bit `pywin32` with a 32-bit Python (or vice-versa) will lead to `ImportError: DLL load failed` or similar issues. ↓

fix Ensure you install the `pywin32` wheel that corresponds to your Python installation's architecture (e.g., `win32.whl` for 32-bit Python, `amd64.whl` for 64-bit Python, though pip usually handles this automatically now). If issues persist, verify your Python environment's bittedness.

gotcha `pywin32` can be challenging to use in embedded Python environments due to how it handles DLL loading, which may cause import failures. ↓

fix For embedded Python distributions, `pywin32` might require specific setup or may not be fully compatible. Consider using a standard Python installation if encountering issues.

gotcha Documentation for `pywin32` is often reported by users as being sparse or outdated, especially for less common functionalities. Adapting VBA examples for COM automation often requires trial and error. ↓

fix Leverage online resources like Stack Overflow, Tim Golden's Python on Windows page, and the official GitHub issue tracker. Experimentation by inspecting COM object methods and attributes at runtime can also be helpful.

gotcha When running Python scripts as Windows services using `pywin32`, ensure that the Python installation and required DLLs are accessible to the user account under which the service runs (e.g., LocalSystem). Permissions issues can prevent services from starting or functioning correctly. ↓

fix Install pywin32 globally from an elevated command prompt. Ensure Python is installed in a location accessible to the service account, not just the user's profile.

breaking `pywin32` is a Windows-specific library that provides access to the Windows API. It cannot be installed or used on non-Windows operating systems (e.g., Linux, macOS) as no distributions exist for those platforms. ↓

fix Ensure you are attempting to install and use `pywin32` in a Windows environment. If cross-platform functionality is needed, consider alternative libraries or different architectural approaches.

breaking `pywin32` is a Windows-specific library and is not available for non-Windows operating systems (e.g., Linux, macOS). Attempting to install it on such platforms will result in `ERROR: No matching distribution found`. ↓

fix Ensure `pywin32` is only installed and used in a Windows environment. If you need to interact with Windows APIs, consider running your application within a Windows container or a Windows virtual machine.

Install compatibility stale last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - - -

3.10 slim (glibc) - - - -

3.11 alpine (musl) - - - -

3.11 slim (glibc) - - - -

3.12 alpine (musl) - - - -

3.12 slim (glibc) - - - -

3.13 alpine (musl) - - - -

3.13 slim (glibc) - - - -

3.9 alpine (musl) - - - -

3.9 slim (glibc) - - - -

Imports

win32com.client
```
import win32com.client
```
Primary module for COM automation (e.g., interacting with Microsoft Office applications).
win32api
```
import win32api
```
Provides access to core Windows API functions (e.g., system information, file operations, process management).
win32serviceutil
```
import win32serviceutil
```
Used for creating and managing Python-based Windows services, often alongside win32service and win32event.
win32clipboard
```
import win32clipboard
```
Module for reading from and writing to the Windows clipboard.

Quickstart stale last tested: 2026-04-23

This quickstart demonstrates basic COM automation by launching Microsoft Excel, making it visible, adding a new workbook, and writing text to specific cells. It showcases the common pattern of using `win32com.client.Dispatch` or `GetActiveObject` to control COM applications. Ensure Excel is installed for this example to run.

import win32com.client
import os

try:
    # Try to get an active Excel instance, or create a new one
    excel = win32com.client.GetActiveObject("Excel.Application")
except Exception: # pythoncom.com_error if pywin32 is installed correctly
    excel = win32com.client.Dispatch("Excel.Application")

excel.Visible = True # Make Excel visible
workbook = excel.Workbooks.Add() # Add a new workbook
sheet = workbook.Sheets(1) # Get the first sheet

sheet.Cells(1, 1).Value = "Hello from pywin32!"
sheet.Cells(2, 1).Value = "Automating Windows with Python."

print("Excel opened and data written. Please check your Excel application.")
print("You might need to close Excel manually after inspection.")