{"id":2678,"library":"pyautogui","title":"PyAutoGUI","description":"PyAutoGUI is a cross-platform Python library for GUI automation, enabling programmatic control of the mouse and keyboard, and other GUI tasks like screenshots and image recognition. It simplifies complex operating system interactions into a straightforward API. Currently at version 0.9.54, the library is actively maintained with updates released periodically.","status":"active","version":"0.9.54","language":"en","source_language":"en","source_url":"https://github.com/asweigart/pyautogui","tags":["GUI automation","mouse","keyboard","screenshot","RPA"],"install":[{"cmd":"pip install pyautogui","lang":"bash","label":"Windows"},{"cmd":"pip3 install pyautogui","lang":"bash","label":"macOS/Linux (Python 3)"}],"dependencies":[{"reason":"Required for screenshot and image recognition functions. Automatically installed via pip.","package":"pyscreeze","optional":false},{"reason":"Required for message box functions (alert, confirm, prompt). Automatically installed via pip.","package":"pymsgbox","optional":false},{"reason":"Required for mouse tweening/easing functions. Automatically installed via pip.","package":"pytweening","optional":false},{"reason":"Provides mouse cursor information. Automatically installed via pip.","package":"mouseinfo","optional":false},{"reason":"Provides window handling functions (e.g., locating, moving, resizing windows). Automatically installed via pip.","package":"pygetwindow","optional":false},{"reason":"Required on macOS for GUI control. Must be installed before pyobjc. Not automatically installed by `pip install pyautogui` on macOS.","package":"pyobjc-core","optional":true},{"reason":"Required on macOS for GUI control. Must be installed after pyobjc-core. Not automatically installed by `pip install pyautogui` on macOS.","package":"pyobjc","optional":true},{"reason":"Required on Linux (for Python 3) for GUI control. Not automatically installed by `pip install pyautogui` on Linux.","package":"python3-xlib","optional":true},{"reason":"Required on Linux for screenshot functions. Must be installed via apt-get or equivalent.","package":"scrot","optional":true},{"reason":"Required on Linux for some GUI elements, notably `pyautogui.screenshot()` and message boxes. Must be installed via apt-get or equivalent.","package":"python3-tk","optional":true},{"reason":"Required on Linux for building some dependencies (e.g., Pillow components). Must be installed via apt-get or equivalent.","package":"python3-dev","optional":true}],"imports":[{"symbol":"pyautogui","correct":"import pyautogui"}],"quickstart":{"code":"import pyautogui\nimport time\n\n# Get screen size\nscreenWidth, screenHeight = pyautogui.size()\nprint(f\"Screen size: {screenWidth}x{screenHeight}\")\n\n# Move mouse to center of screen\npyautogui.moveTo(screenWidth / 2, screenHeight / 2, duration=1)\n\n# Click at current position\npyautogui.click()\n\n# Type a message (simulates keyboard input)\npyautogui.write('Hello, PyAutoGUI!', interval=0.1)\n\n# Press a hotkey combination (e.g., Ctrl+S to save)\n# pyautogui.hotkey('ctrl', 's')\n\n# Display an alert box\npyautogui.alert('Automation script finished!\\nClick OK to exit.')","lang":"python","description":"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."},"warnings":[{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`).","message":"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.","severity":"breaking","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}