Registry / serialization / comtypes

comtypes

JSON →
library1.4.16pypypi✓ verified 25d ago

comtypes is a lightweight pure Python COM package based on the ctypes foreign function interface library. It allows defining, calling, and implementing custom and dispatch-based COM interfaces in pure Python. It currently requires Windows and Python 3.9 or later, with version 1.4.16 being the latest release. The project has an active release cadence with regular updates and maintenance.

pip install comtypes
INSTALL
IMPORT
SIG · COMTYPES
C
comtypes
serializationpythonv1.4.16
Install
1.7s avg
Import
Disk
18MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.4.16 · 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
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 20.2MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 1.7s · import 0.000s · 21MB
18MB installed
● package 18MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

CreateObject
from comtypes.client import CreateObject
from comtypes.client import CreateObject

This quickstart demonstrates how to create and interact with a COM object using `comtypes.client.CreateObject`. It attempts to instantiate the `MSScriptControl.ScriptControl` object, which provides scripting capabilities, and then executes a simple JavaScript expression. Error handling is included for when the COM object might not be available on the system.

import comtypes.client import comtypes # This example creates a COM object for the Microsoft Script Control, # which might not be installed by default on all Windows systems. # It's used here as a common demonstration of COM object creation. try: # Create an instance of a COM object using its ProgID engine = comtypes.client.CreateObject("MSScriptControl.ScriptControl") print("Successfully created MSScriptControl.ScriptControl object.") # Use the COM object (example: evaluate a JScript expression) engine.Language = "JScript" result = engine.Eval("100 * 2") print(f"Result of '100 * 2': {result}") # If you need to access a specific interface by IID (Interface ID) # from comtypes.GUID import GUID # IID_IDispatch = GUID("{00020400-0000-0000-C000-000000000046}") # disp_interface = engine.QueryInterface(IID_IDispatch) # print(f"Queried for IDispatch interface: {disp_interface}") except comtypes.COMError as e: print(f"COM Error occurred: {e}") print("This often means the requested COM object (e.g., MSScriptControl.ScriptControl)") print("is not registered or available on your Windows system.") except Exception as e: print(f"An unexpected error occurred: {e}")
Debug
Known issues
breakingcomtypes now requires Python 3.9 or later. Version 1.4.12 was the last release to officially support Python 3.8. Users on older Python versions must upgrade or use an older comtypes version.
fix
Upgrade Python to 3.9+ or pin comtypes version to <=1.4.12 for Python 3.8.
affects: <1.4.13
deprecatedThe `logutil.setup_logging` function has been deprecated. It should be replaced with standard Python `logging` module configuration.
fix
Migrate logging setup to use Python's built-in `logging` module functions and configurations.
affects: >=1.4.16
gotchaGenerated type library wrapper modules (in `comtypes.gen`) can sometimes become corrupted or outdated, leading to `ImportError`, `NameError`, or `SyntaxError`.
fix
Run `python -m comtypes.clear_cache` to delete and regenerate the cached modules. This often resolves such import-related issues.
affects: All
gotchacomtypes is a Windows-only library due to its reliance on the Component Object Model (COM), which is a Microsoft technology. It will not function on other operating systems.
fix
Ensure the application runs on a Microsoft Windows operating system.
affects: All
gotchaDirect usage of `ctypes.windll` or `ctypes.oledll` (from `ctypes`) should be modernized to `ctypes.WinDLL` or `ctypes.OleDLL` for improved robustness and clarity in current Python versions.
fix
Replace `windll.<function>` with `WinDLL('library').<function>` and `oledll.<function>` with `OleDLL('library').<function>`.
affects: All
gotchaStarting with Python 3.15, the internal handling of `IntFlag` (Flag) values is planned to change. This may affect enumeration types generated by `comtypes` from COM type libraries, potentially reinterpreting negative `IntFlag` members.
fix
Review `comtypes`-generated enumeration types when migrating to Python 3.15+ and consult `comtypes` documentation/issues for potential workarounds or updates (GH-894).
affects: >=3.15 (Python)
Upgrade
Version history
1.4.16latest on PyPI · released Mar 2, 2026
Audit
Dependencies
numpyoptionalOptional: to process arrays as numpy's ndarray.
mypyoptionalOptional: for static type checking of generated type hints.
Agent activity
46 hits · last 30 days
node
42
OpenAI (training)
1
Resources