Install & Compatibility
Where this runs
tested against v312.0.0.20260609 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 20.5MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.6s · import 0.000s · 21MB
18MB installed
● package 18MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
win32api
✓ from win32-stubs import win32api
✗ import win32-stubs.win32api
This quickstart demonstrates typical usage of `pywin32` and how `types-pywin32` silently provides type annotations for static analysis tools. You do not import `types-pywin32` directly; rather, its presence enables type checkers to understand the `pywin32` API.
import win32api
import win32con
from typing import TYPE_CHECKING
import os
# types-pywin32 provides type information for pywin32 modules like win32api.
# It is not imported directly into your runtime code.
# Its benefits are seen when running a static type checker (e.g., mypy, pyright).
# Example 1: Getting a Windows system directory with type hint
windows_directory: str = win32api.GetWindowsDirectory()
print(f"Windows Directory: {windows_directory}")
# Example 2: Using a constant from win32con and a function from win32api
# The actual MessageBox call is commented out to prevent interactive prompts
# during automated tests or in non-interactive environments.
if TYPE_CHECKING:
# Type checkers will use the stubs for win32api.MessageBox here.
# In a real application, you'd ensure the function call arguments match
# the stub definitions provided by types-pywin32.
pass
else:
try:
# Example of a win32api call (commented out for quickstart execution)
# win32api.MessageBox(0, "Hello from pywin32!", "Pywin32 Example", win32con.MB_OK)
print("MessageBox call skipped in quickstart to avoid UI interaction.")
except Exception as e:
print(f"Could not display message box (expected if not on Windows or interactive): {e}")
print("Static type checking for pywin32 is enhanced by types-pywin32.")
Debug
Known issues
breakingType stubs are versioned to align with specific `pywin32` major versions. If `pywin32` undergoes a major API change, `types-pywin32` will update to reflect the new API, potentially causing type-checking errors for code using older `pywin32` versions.fixEnsure the installed `types-pywin32` version matches the `pywin32` version you are using (e.g., `types-pywin32==311.*` for `pywin32==311.*`). Pin both dependencies in your project.
affects: All versions, especially across `pywin32` major releases
gotchaThe underlying `pywin32` library often requires a post-install script (`python -m pywin32_postinstall -install`) to register COM components and place DLLs. Failure to run this, especially in virtual environments or when running as a Windows Service, can lead to runtime errors even if `types-pywin32` is correctly installed.fixAfter installing `pywin32`, run `python -m pywin32_postinstall -install` from an elevated command prompt outside of a virtual environment for global installs, or ensure proper environment setup for virtual environments or services. Verify `PATH` settings.
affects: All versions of pywin32, implicitly affecting types-pywin32 users.
gotchaSome `pywin32` functions may exhibit incorrect parameter resolution or `reportCallIssue` warnings in type checkers (e.g., Pylance) due to stubs defining parameters as positional-only when they are commonly used as keyword arguments, or other discrepancies in stub definitions.fixRefer to the official `pywin32` documentation or typeshed for the exact expected parameter signature. If necessary, create a local stub override or contribute a fix to typeshed. Consider using positional arguments if keyword arguments are not recognized by the type checker.
affects: All versions of types-pywin32 (depends on specific function stub).
gotchaWhen bundling applications with tools like PyInstaller, users may encounter `win32ctypes.pywin32.pywintypes.error`. This typically indicates issues with the `pywin32` installation, version incompatibilities with PyInstaller, or incorrect PATH configurations for its DLLs.fixEnsure correct `pywin32` installation, try reinstalling `pywin32`, manually running the `pywin32_postinstall` script, or testing with specific PyInstaller versions known to be compatible. Ensure the environment `PATH` is correctly configured.
affects: All versions of pywin32, especially when used with PyInstaller.
deprecatedUsers might encounter `DeprecationWarning: getargs: The 'u' format is deprecated. Use 'U' instead` originating from `pywintypes.py` within `pywin32`. This indicates internal usage of an older Python C API format for Unicode, which has a newer, preferred alternative.fixThis warning typically comes from the `pywin32` library itself and often does not impact functionality. Ensure you are using a recent version of `pywin32` and Python, as updates to `pywin32` may address this internally.
affects: Older versions of Python with newer pywin32, or specific pywin32 builds.
Upgrade
Version history
312.0.0.20260609latest on PyPI · released Jun 9, 2026
Audit
Dependencies
pywin32requiredRuntime library for which these stubs provide type information.
mypyoptionalCommon static type checker that utilizes these stubs.
pyrightoptionalAnother common static type checker that utilizes these stubs.