pywinauto

Windows UI automation (pywinauto)

Operate any Windows desktop application via pywinauto: discover windows, inspect controls, click buttons, enter text, read content. Supports two backends: Win32 API (legacy applications) and MS UI Automation (modern applications).

Use cases

• The user says "help me click that button in XX application" or "auto-fill this form"
• Need to operate desktop applications that have no API (such as ERP systems, internal management systems)
• Need to batch-operate GUI applications (such as automated data entry)
• Need to read text content on other applications' interfaces

Backend selection

Backend	Parameter	Applicable applications
Win32 API	backend="win32"	MFC, VB6, VCL, simple WinForms
MS UI Automation	backend="uia"	WinForms, WPF, UWP Store applications, Qt5, browsers

When unsure which to use, try uiafirst; if no controls are found, switch to win32。

Command reference

Connect to an existing application

from pywinauto import Application

# 方式 1：通过窗口标题连接
app = Application(backend="uia").connect(title="记事本", timeout=10)

# 方式 2：通过进程名连接
app = Application(backend="uia").connect(path="notepad.exe")

# 方式 3：通过进程 ID 连接
app = Application(backend="uia").connect(process=12345)

Launch a new application

from pywinauto import Application

app = Application(backend="uia").start("notepad.exe")
# 等待窗口出现
app.window(title_re=".*记事本.*").wait("ready", timeout=10)

Discover windows and controls

# 列出所有顶层窗口
from pywinauto import Desktop
windows = Desktop(backend="uia").windows()
for w in windows:
    print(f"{w.window_text()} — {w.class_name()}")

# 打印窗口控件树（调试用）
dlg = app.window(title_re=".*记事本.*")
dlg.print_control_identifiers()

Click buttons and menus

dlg = app.window(title="记事本")

# 点击菜单
dlg.menu_select("文件->打开")

# 点击按钮（通过文本匹配）
dlg.child_window(title="确定", control_type="Button").click()

# 点击按钮（通过 auto_id）
dlg.child_window(auto_id="btnSubmit").click()

Enter text

dlg = app.window(title="记事本")

# 输入到编辑框
edit = dlg.child_window(control_type="Edit")
edit.set_text("要输入的内容")

# 模拟键盘输入（支持特殊键）
edit.type_keys("Hello{ENTER}World", with_spaces=True)

# 特殊键：{ENTER} {TAB} {ESC} {DELETE} {BACKSPACE}
# 修饰键：^ = Ctrl, % = Alt, + = Shift
# 例：Ctrl+A = ^a, Ctrl+Shift+S = ^+s

Read interface content

dlg = app.window(title="记事本")

# 读取文本框内容
content = dlg.child_window(control_type="Edit").window_text()

# 读取列表项
listbox = dlg.child_window(control_type="List")
items = [item.window_text() for item in listbox.children()]

# 读取表格
table = dlg.child_window(control_type="Table")
for row in table.children():
    cells = [c.window_text() for c in row.children()]
    print(" | ".join(cells))

Waiting and synchronization

# 等待窗口出现
dlg = app.window(title="保存").wait("visible", timeout=10)

# 等待窗口消失
app.window(title="加载中...").wait_not("visible", timeout=30)

# 等待控件可用
dlg.child_window(title="提交").wait("enabled", timeout=5)

Window management

dlg = app.window(title="记事本")

# 最大化 / 最小化 / 还原
dlg.maximize()
dlg.minimize()
dlg.restore()

# 移动和调整大小
dlg.move_window(x=100, y=100, width=800, height=600)

# 置顶
dlg.set_focus()

# 关闭
dlg.close()

Scrolling

from pywinauto import mouse

# 向下滚动 3 格（在指定坐标位置）
mouse.scroll(coords=(500, 400), wheel_dist=-3)

# 向上滚动 5 格
mouse.scroll(coords=(500, 400), wheel_dist=5)

# 在控件内滚动（先获取控件位置）
rect = dlg.child_window(control_type="List").rectangle()
mouse.scroll(coords=(rect.mid_point()), wheel_dist=-3)

Mouse coordinate operations

from pywinauto import mouse

# 移动鼠标到坐标
mouse.move(coords=(500, 300))

# 在指定坐标左键点击
mouse.click(coords=(500, 300))

# 右键点击
mouse.right_click(coords=(500, 300))

# 双击
mouse.double_click(coords=(500, 300))

Drag and drop

from pywinauto import mouse

# 拖拽：从 (100,200) 到 (300,400)
mouse.press(coords=(100, 200))
mouse.move(coords=(300, 400))
mouse.release(coords=(300, 400))

Typical workflow

1. 用 Desktop().windows() 列出当前打开的窗口
2. 用 app.connect() 连接到目标应用
3. 用 dlg.print_control_identifiers() 查看控件树
4. 根据控件类型和属性定位目标元素
5. 执行操作（click / set_text / type_keys / scroll）
6. 读取结果或等待操作完成

Safety rules

• HITL confirmation is required before operations: inform the user which control of which application is about to be operated
• Do not automatically close user documents: do not call close() on documents that have not been saved
• Do not operate administrator windows: skip UAC pop-ups and system settings
• Provide screenshot feedback when an operation fails: let the user see the current interface state
• Interval of 0.5 seconds between each operation: avoid operating too quickly and causing the UI to not have time to respond