pyautogui

library0.9.54pypypi✓ verified 26d ago

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.

testing ai-ml

pip install pyautogui

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PYAUTOGUI

pyautogui

testingpythonv0.9.54

Install

9.1s avg

Import

—

Disk

30MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.9.54 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.000s · 40.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 9.1s · import 0.000s · 42MB

30MB installed

● package 30MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

pyautogui

✓ import pyautogui

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.')

Debug

Known issues

gotchaPyAutoGUI 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`.

affects: All versions

breakingPlatform-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`).

affects: All versions

gotchaThe `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.

affects: All versions

gotchaPyAutoGUI 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.

affects: All versions

gotchaPyAutoGUI 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.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'pyautogui'

The 'pyautogui' module is not installed in the Python environment being used.

fix

Install the module using 'pip install pyautogui'.

ImportError: No module named 'pyautogui'

The 'pyautogui' module is not installed or is installed in a different Python environment.

fix

Ensure 'pyautogui' is installed in the correct environment using 'pip install pyautogui'.

ImportError: No module named pyautogui

The 'pyautogui' module is not installed or is installed in a different Python environment.

fix

Ensure 'pyautogui' is installed in the correct environment using 'pip install pyautogui'.

No module named 'pyautogui'

The 'pyautogui' module is not installed or is installed in a different Python environment.

fix

Ensure 'pyautogui' is installed in the correct environment using 'pip install pyautogui'.

pyautogui.PyAutoGUIException: PyAutoGUI was unable to import pyscreeze.

PyAutoGUI's screenshot and image recognition functionalities depend on the 'pyscreeze' library, which in turn relies on 'Pillow' and often 'opencv-python'. This error typically occurs if these dependencies are missing, outdated, or incompatible with the Python version.

fix

Ensure Pillow and opencv-python are installed and up-to-date: `pip install --upgrade Pillow opencv-python`.

Upgrade

Version history

0.9.54latest on PyPI · released May 24, 2023

Audit

Dependencies

pyscreezerequiredRequired for screenshot and image recognition functions. Automatically installed via pip.

pymsgboxrequiredRequired for message box functions (alert, confirm, prompt). Automatically installed via pip.

pytweeningrequiredRequired for mouse tweening/easing functions. Automatically installed via pip.

mouseinforequiredProvides mouse cursor information. Automatically installed via pip.

pygetwindowrequiredProvides window handling functions (e.g., locating, moving, resizing windows). Automatically installed via pip.

pyobjc-coreoptionalRequired on macOS for GUI control. Must be installed before pyobjc. Not automatically installed by `pip install pyautogui` on macOS.

pyobjcoptionalRequired on macOS for GUI control. Must be installed after pyobjc-core. Not automatically installed by `pip install pyautogui` on macOS.

python3-xliboptionalRequired on Linux (for Python 3) for GUI control. Not automatically installed by `pip install pyautogui` on Linux.

scrotoptionalRequired on Linux for screenshot functions. Must be installed via apt-get or equivalent.

python3-tkoptionalRequired on Linux for some GUI elements, notably `pyautogui.screenshot()` and message boxes. Must be installed via apt-get or equivalent.

python3-devoptionalRequired on Linux for building some dependencies (e.g., Pillow components). Must be installed via apt-get or equivalent.

Agent activity

8 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/asweigart/pyautogui ↗

packagehttps://pypi.org/project/pyautogui/ ↗

homepagehttps://pyautogui.readthedocs.org ↗