pywinauto

pywinauto is a set of Python modules for automating the Microsoft Windows GUI. Rather than relying on pixel coordinates, it identifies windows and controls by their text properties (titles, classnames, control IDs), which makes automation scripts more readable and resilient to layout changes. It supports two backends under the hood: the legacy Win32 API (the default) and MS UI Automation (backend="uia"), so it can drive both classic Win32 dialogs and modern WPF/UWP-style controls from the same API surface.

A typical script starts or connects to an application with Application(), then addresses dialogs and controls through attribute access or child_window() lookups that use fuzzy best-match text matching rather than exact strings. This lets a script write app.UntitledNotepad.Edit.type_keys(...) without needing pixel-perfect titles. Beyond GUI element manipulation, pywinauto ships standalone mouse and keyboard input-emulation modules that work on both Windows and Linux, plus a growing atspi-based Linux backend, positioning it as a cross-platform desktop automation toolkit rather than a Windows-only tool.

What You Get

• Two pluggable backends (win32 and uia) so the same API can drive classic Win32 dialogs and modern UI Automation-based controls
• Fuzzy best-match text lookup for windows and controls (findbestmatch), so scripts don’t need exact, brittle title strings
• A dotted/attribute-style API (app.Dialog.Control.action()) plus an explicit child_window(title=..., class_name=..., ...) lookup for precise matches
• Standalone mouse and keyboard input-emulation modules usable independently of the window-matching layer, on both Windows and Linux
• Wrapper classes for common Win32 and UIA control types (buttons, menus, common controls) exposing native methods like .click(), .type_keys(), and .get_item()
• Utilities for printing a dialog’s full control identifier tree (print_control_identifiers()), which speeds up writing new automation scripts

Common Use Cases

• Automated UI regression testing of Windows desktop applications in CI pipelines
• Robotic process automation (RPA) scripts that operate legacy Windows line-of-business software with no API
• Scripted end-to-end smoke tests that launch an app, navigate dialogs, and assert on control state
• Data entry or repetitive-task automation for desktop apps without exposing an API
• Exploratory tooling for inspecting the accessibility/control tree of an unfamiliar Windows application

Under The Hood

Architecture pywinauto is organized as a backend-registry pattern: backend.py defines a BackEnd descriptor (name, element_info_class, generic_wrapper_class) and a BackendsRegistry that platform-specific modules populate at import time, while base_application.py’s WindowSpecification and base_wrapper.py’s BaseWrapper define the platform-agnostic contract every backend must satisfy. The top-level application.py is a thin dispatcher that imports windows.application.Application on win32 and linux.application.Application elsewhere, so the public API stays constant while windows/, linux/, and controls/ (with win32_controls.py, uia_controls.py, atspi_controls.py, wpf_controls.py) supply concrete element-info and control-wrapper implementations. Control and window lookup runs through findwindows.py and findbestmatch.py, which apply fuzzy text-similarity matching rather than exact string comparison, so the attribute-style API (app.Dialog.Control) resolves against real running windows without brittle exact titles. Swapping the active backend (win32 vs uia vs atspi) is the core abstraction that would ripple furthest if changed, since every wrapper and control subclass is keyed off it.

Tech Stack The library targets Python 2.7 and 3.5+ per its classifiers, built with plain setuptools (setup.py, no pyproject.toml). Platform-conditional extras_require pull in comtypes and pywin32 on Windows (pinned by Python version for older interpreters) and python-xlib on Linux, keeping the core package free of hard platform dependencies. Optional Pillow support enables capture_as_image() for control snapshots. The dev toolchain (dev-requirements.txt) pins pytest, pytest-cov, coverage, codecov, mock, Sphinx/rst2pdf for docs, and PyQt5 fixtures used by the UI Automation test suite. No modern build backend (Poetry/Hatch) or type-checker config is present.

Code Quality The pywinauto/unittests/ directory holds roughly three dozen test modules covering nearly every subsystem (test_application.py, test_findbestmatch.py, test_hwndwrapper.py, test_uiawrapper.py, test_atspi_*, test_win32*, etc.), run via both AppVeyor (Windows) and GitHub Actions (Linux/atspi) with coverage/codecov reporting, indicating an extensive and platform-aware test suite rather than a token one. Error handling favors explicit custom exceptions (InvalidElement, ElementNotEnabled, ElementNotVisible, MatchError) raised from clearly named guard conditions instead of silent failures. There is no static typing (no type hints, no mypy config) and no linter/formatter configuration checked in, so code style consistency relies on convention and review rather than enforced tooling.

API Design The public surface is deliberately ergonomic for scripting: Application().start("notepad.exe") followed by dotted attribute chains (app.UntitledNotepad.Edit.type_keys(...)) reads close to natural language, and print_control_identifiers() gives users a fast way to discover selectors for a dialog they’ve never scripted before, lowering the barrier to writing a first automation. The fuzzy-match layer means small UI text differences don’t break scripts, which is a meaningful DX win over automation libraries requiring exact accessibility-tree matches, though the trade-off is that behavior can occasionally match an unintended control silently rather than raising immediately.