{"id":571,"library":"pywin32","title":"pywin32 (Python for Windows Extensions)","description":"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.","status":"active","version":"311","language":"python","source_language":"en","source_url":"https://github.com/mhammond/pywin32","tags":["windows","system","automation","COM","winapi","office"],"install":[{"cmd":"pip install pywin32 --upgrade","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required for some COM object creation and interaction functionalities, though often pre-installed on modern Windows systems.","package":"Visual C++ Redistributable for Visual Studio","optional":true}],"imports":[{"note":"Primary module for COM automation (e.g., interacting with Microsoft Office applications).","symbol":"win32com.client","correct":"import win32com.client"},{"note":"Provides access to core Windows API functions (e.g., system information, file operations, process management).","symbol":"win32api","correct":"import win32api"},{"note":"Used for creating and managing Python-based Windows services, often alongside win32service and win32event.","symbol":"win32serviceutil","correct":"import win32serviceutil"},{"note":"Module for reading from and writing to the Windows clipboard.","symbol":"win32clipboard","correct":"import win32clipboard"}],"quickstart":{"code":"import win32com.client\nimport os\n\ntry:\n    # Try to get an active Excel instance, or create a new one\n    excel = win32com.client.GetActiveObject(\"Excel.Application\")\nexcept Exception: # pythoncom.com_error if pywin32 is installed correctly\n    excel = win32com.client.Dispatch(\"Excel.Application\")\n\nexcel.Visible = True # Make Excel visible\nworkbook = excel.Workbooks.Add() # Add a new workbook\nsheet = workbook.Sheets(1) # Get the first sheet\n\nsheet.Cells(1, 1).Value = \"Hello from pywin32!\"\nsheet.Cells(2, 1).Value = \"Automating Windows with Python.\"\n\nprint(\"Excel opened and data written. Please check your Excel application.\")\nprint(\"You might need to close Excel manually after inspection.\")","lang":"python","description":"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."},"warnings":[{"fix":"Always use `pip install pywin32` or `python -m pip install pywin32` for installation instead of .exe files.","message":"Binary .exe installers for pywin32 have been deprecated since build 306. Installation should now be performed using pip.","severity":"breaking","affected_versions":">=306"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"`pywin32` can be challenging to use in embedded Python environments due to how it handles DLL loading, which may cause import failures.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"`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.","severity":"breaking","affected_versions":"All versions"},{"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.","message":"`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`.","severity":"breaking","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T15:26:15.450Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"pip install pywin32","cause":"The pywin32 library is not installed in the current Python environment, or its post-installation scripts did not run successfully.","error":"ModuleNotFoundError: No module named 'win32api'"},{"fix":"Verify the correct ProgID for the desired application and ensure the application is installed and correctly registered on the system.","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.","error":"pywintypes.com_error: (-2147221005, 'Invalid class string', None, None)"},{"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`).","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).","error":"AttributeError: <COM object win32com.client.Dispatch of type <unknown>>.Workbooks"},{"fix":"Convert the argument to the expected type, typically an integer (`int()`), a specific `pywin32` constant, or `None` for null pointers.","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).","error":"TypeError: Argument 'hwndParent' must be an integer"},{"fix":"Run `python -m pywin32_postinstall -install` from an administrator command prompt to ensure all `pywin32` components are correctly registered.","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`.","error":"python -m pywin32_postinstall"}],"ecosystem":"pypi","meta_description":null,"install_score":0,"install_tag":"stale","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}