PyAutoGUI

Warnings

• gotcha PyAutoGUI includes a fail-safe feature. Moving the mouse cursor to any of the four corners of the primary monitor will immediately raise a `pyautogui.FailSafeException` to stop runaway scripts. This feature is enabled by default and highly recommended to keep on.
  Fix: Be aware of this feature. To disable (NOT recommended), set `pyautogui.FAILSAFE = False`. Adjust the default 0.1-second delay between calls with `pyautogui.PAUSE = value`.
• breaking Platform-specific dependencies are often required but not automatically installed by `pip` on macOS or Linux. Missing these can prevent core features (like screenshots or keyboard control) from working.
  Fix: Manually install required OS packages (e.g., `pyobjc-core` and `pyobjc` on macOS; `python3-xlib`, `scrot`, `python3-tk`, `python3-dev` on Linux) using your system's package manager (`pip3` or `apt-get`).
• gotcha The `pyautogui.typewrite()` function may not correctly handle non-US keyboard layouts or special characters/symbols, often producing incorrect input or failing for Unicode strings.
  Fix: For reliable text input with non-US layouts or complex strings, consider using an external library like `keyboard` (e.g., `keyboard.write(text)`) or copying text to the clipboard and then pasting it using `pyautogui.hotkey('ctrl', 'v')` or equivalent.
• gotcha PyAutoGUI may not function reliably inside virtual machines (VMs), sometimes controlling the host machine instead of the guest OS. This can lead to scripts executing without visible actions within the VM.
  Fix: Ensure proper VM setup for GUI automation. This often involves specific guest additions/tools installation and configuration to allow the VM to intercept and process host input correctly. Running PyAutoGUI in a VM may require additional troubleshooting specific to your VM software.
• gotcha PyAutoGUI reliably operates only on the primary monitor. Its behavior with secondary or multiple monitor setups can be inconsistent, with mouse functions potentially failing or targeting the wrong screen depending on the operating system and its version.
  Fix: Design scripts to operate within the bounds of the primary monitor or run the automation on systems with a single display for consistent results.

Install

• pip install pyautogui Windows
• pip3 install pyautogui macOS/Linux (Python 3)

Imports

• pyautogui

  import pyautogui

Quickstart

This quickstart demonstrates basic PyAutoGUI functions: getting screen dimensions, moving the mouse, clicking, typing text, and displaying a message box. The `duration` and `interval` parameters add human-like delays.

import pyautogui
import time

# Get screen size
screenWidth, screenHeight = pyautogui.size()
print(f"Screen size: {screenWidth}x{screenHeight}")

# Move mouse to center of screen
pyautogui.moveTo(screenWidth / 2, screenHeight / 2, duration=1)

# Click at current position
pyautogui.click()

# Type a message (simulates keyboard input)
pyautogui.write('Hello, PyAutoGUI!', interval=0.1)

# Press a hotkey combination (e.g., Ctrl+S to save)
# pyautogui.hotkey('ctrl', 's')

# Display an alert box
pyautogui.alert('Automation script finished!\nClick OK to exit.')