{"id":2445,"library":"comtypes","title":"Pure Python COM package","description":"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.","status":"active","version":"1.4.16","language":"en","source_language":"en","source_url":"https://github.com/enthought/comtypes","tags":["COM","Windows","ctypes","automation","interoperability"],"install":[{"cmd":"pip install comtypes","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Optional: to process arrays as numpy's ndarray.","package":"numpy","optional":true},{"reason":"Optional: for static type checking of generated type hints.","package":"mypy","optional":true}],"imports":[{"note":"Used for creating instances of COM objects by ProgID or CLSID.","symbol":"CreateObject","correct":"from comtypes.client import CreateObject"},{"note":"Used to generate Python wrapper modules from COM type libraries (.tlb, .exe, .dll).","symbol":"GetModule","correct":"from comtypes.client import GetModule"},{"note":"Lower-level function for creating a single uninitialized object of the class associated with a specified CLSID.","symbol":"CoCreateInstance","correct":"from comtypes import CoCreateInstance"},{"note":"Represents a COM GUID (Globally Unique Identifier).","symbol":"GUID","correct":"from comtypes import GUID"}],"quickstart":{"code":"import comtypes.client\nimport comtypes\n\n# This example creates a COM object for the Microsoft Script Control,\n# which might not be installed by default on all Windows systems.\n# It's used here as a common demonstration of COM object creation.\n\ntry:\n    # Create an instance of a COM object using its ProgID\n    engine = comtypes.client.CreateObject(\"MSScriptControl.ScriptControl\")\n    print(\"Successfully created MSScriptControl.ScriptControl object.\")\n\n    # Use the COM object (example: evaluate a JScript expression)\n    engine.Language = \"JScript\"\n    result = engine.Eval(\"100 * 2\")\n    print(f\"Result of '100 * 2': {result}\")\n\n    # If you need to access a specific interface by IID (Interface ID)\n    # from comtypes.GUID import GUID\n    # IID_IDispatch = GUID(\"{00020400-0000-0000-C000-000000000046}\")\n    # disp_interface = engine.QueryInterface(IID_IDispatch)\n    # print(f\"Queried for IDispatch interface: {disp_interface}\")\n\nexcept comtypes.COMError as e:\n    print(f\"COM Error occurred: {e}\")\n    print(\"This often means the requested COM object (e.g., MSScriptControl.ScriptControl)\")\n    print(\"is not registered or available on your Windows system.\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade Python to 3.9+ or pin comtypes version to <=1.4.12 for Python 3.8.","message":"comtypes 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.","severity":"breaking","affected_versions":"<1.4.13"},{"fix":"Migrate logging setup to use Python's built-in `logging` module functions and configurations.","message":"The `logutil.setup_logging` function has been deprecated. It should be replaced with standard Python `logging` module configuration.","severity":"deprecated","affected_versions":">=1.4.16"},{"fix":"Run `python -m comtypes.clear_cache` to delete and regenerate the cached modules. This often resolves such import-related issues.","message":"Generated type library wrapper modules (in `comtypes.gen`) can sometimes become corrupted or outdated, leading to `ImportError`, `NameError`, or `SyntaxError`.","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure the application runs on a Microsoft Windows operating system.","message":"comtypes 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.","severity":"gotcha","affected_versions":"All"},{"fix":"Replace `windll.<function>` with `WinDLL('library').<function>` and `oledll.<function>` with `OleDLL('library').<function>`.","message":"Direct 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.","severity":"gotcha","affected_versions":"All"},{"fix":"Review `comtypes`-generated enumeration types when migrating to Python 3.15+ and consult `comtypes` documentation/issues for potential workarounds or updates (GH-894).","message":"Starting 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.","severity":"gotcha","affected_versions":">=3.15 (Python)"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}