README.md

comtypes

About

comtypes is a lightweight Python COM package, based on the ctypes FFI library.

comtypes allows to define, call, and implement custom and dispatch-based COM interfaces in pure Python.

This package works on Windows only.

Available on Python 3.7-3.12.

• comtypes==1.2.1 is the last version supporting Python 2.7 and 3.3-3.6.
• In Python 3.7.6 and 3.8.1, comtypes would not work as reported in GH-202.
  This bug has been fixed in Python >= 3.7.7 and >= 3.8.2.
• In Python 3.8 and 3.9, some of comtypes functionalities may not work correctly as reported in GH-212.
  This bug has been fixed in Python >= 3.10.10 and >= 3.11.2.

Where to get it

The source code is currently hosted on GitHub at: https://github.com/enthought/comtypes

An installer for the latest released version is available at the Python Package Index (PyPI).

# PyPI
pip install comtypes

Dependencies

comtypes requires no third-party packages to run - this is truly pure Python package.

Optional features include the follows...

• to process arrays as numpy's ndarray
• type hints be interpreted by mypy or several static type checkers

But these third-parties are not required as a prerequisite for runtime.

Community of the developers

Tracking issues, reporting bugs and contributing to the codebase and documentation are on GitHub at: https://github.com/enthought/comtypes

For Enterprise

Available as part of the Tidelift Subscription.

This project and the maintainers of thousands of other packages are working with Tidelift to deliver one enterprise subscription that covers all of the open source you use.

Learn more.

Frequently Asked Questions

Q: Why does this package not support platforms other than Windows?

A: The Microsoft Component Object Model (COM) is a technology that is unique to Windows and is not supported on other platforms.

The phrase "COM is a platform-independent" in the MS documentation means that COM maintains compatibility across different versions of Windows, and does NOT imply that it is supported on Linux or Mac.

As long as COM is not supported outside of Windows, this project does not plan to port to other platforms.

Q: Why does cannot import name 'COMError' from '_ctypes' error occur when using this package on platforms other than Windows?

A: The _ctypes is part of the internal implementation of the ctypes standard library that exists for Python on all platforms.
However, COMError and COM-related features are implemented only in Python for Windows.

In cross-platform software development, care must be taken to ensure that codebase dependent on comtypes does not execute in environments other than Windows.

Q: Despite a script that depends on comtypes having run successfully before, a error (ImportError, NameError, or SyntaxError) is raised now, and the same error occurs again and again.

A: Executing py -m comtypes.clear_cache and then running the script again might resolve the problem.

When comtypes.client.GetModule is called (either directly or indirectly), comtypes generates Python module files.
If Python is forced to terminate or crashes in the middle of file generation, the codebase written to the file becomes partial.
When Python tries to import this unexecutable partial codebase module, an error occurs.

Executing py -m comtypes.clear_cache identifies the directories where the "cache module files" are stored and deletes them.
After deleting these partial modules and running the script again, comtypes.client.GetModule is called and executable modules are generated anew.

However, if the script implementation does not use comtypes.client.GetModule or processes generated files, it may not be a solution.

Documentation:

The documentation is currently hosted on pythonhosted at: https://pythonhosted.org/comtypes