Introduction to pyautogui

diagram a GUI script drives the whole machine, not just your program mermaid

  flowchart TD
  A["your script types and clicks"] --> B{"is the intended window focused?"}
  B -->|no| C["the input goes somewhere else entirely"]
  B -->|yes| D["the action lands where you meant"]
  E["FAILSAFE = True"] --> F["slam the mouse into a corner to abort"]
  G["pyautogui.PAUSE"] --> H["a delay after every call, so you can watch it"]
  I["locateOnScreen before clicking"] --> J{"found?"}
  J -->|no| K["stop -- do not click blind coordinates"]
  J -->|yes| D
  C --> L["this is why you test on a machine you can afford to disturb"]

pyautogui has no idea what it is clicking. It moves the real cursor and types into whatever has focus, so a window appearing at the wrong moment redirects the input somewhere unintended. Everything about writing these safely is about keeping a way to stop and never assuming what is on screen.

Warning

GUI automation can click/delete the wrong things.

• keep failsafes
• prefer APIs when possible

Basic controls

pyautogui_basics.py

import pyautogui
 
print(pyautogui.size())
print(pyautogui.position())

Failsafe

By default, moving the mouse to the top-left corner raises pyautogui.FailSafeException.

Keep it enabled.