or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdkeyboard-input.mdmessage-boxes.mdmouse-control.mdscreen-image.mdutilities.mdwindow-management.md
tile.json

tessl/pypi-pyautogui

Cross-platform GUI automation library that enables programmatic control of mouse, keyboard, and screen interactions.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/pyautogui@0.9.x

To install, run

npx @tessl/cli install tessl/pypi-pyautogui@0.9.0

index.mddocs/

PyAutoGUI

A cross-platform GUI automation library that enables programmatic control of mouse movements, clicks, keyboard input, and screen interactions across Windows, macOS, and Linux operating systems. PyAutoGUI provides a unified API for performing GUI automation tasks including mouse positioning and clicking, keyboard input simulation, screenshot capture and image recognition, message box displays, and window management operations.

Package Information

  • Package Name: PyAutoGUI
  • Language: Python
  • Installation: pip install pyautogui
  • Version: 0.9.54
  • Documentation: https://pyautogui.readthedocs.org

Core Imports

import pyautogui

All functions and constants are available directly from the main module:

# Common import pattern
import pyautogui

# Access all functions directly
pyautogui.click(100, 200)
pyautogui.typewrite('Hello World')
pyautogui.screenshot()

Basic Usage

import pyautogui
import time

# Configure failsafe (move mouse to top-left corner to abort)
pyautogui.FAILSAFE = True
pyautogui.PAUSE = 1  # 1 second pause between actions

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

# Mouse operations
pyautogui.click(100, 200)  # Click at coordinates
pyautogui.rightClick(300, 400)  # Right-click
pyautogui.doubleClick(150, 250)  # Double-click

# Keyboard operations
pyautogui.typewrite('Hello, World!')  # Type text
pyautogui.press('enter')  # Press a key
pyautogui.hotkey('ctrl', 'c')  # Keyboard shortcut

# Screen capture and image recognition
screenshot = pyautogui.screenshot()
button_location = pyautogui.locateOnScreen('button.png')
if button_location:
    pyautogui.click(button_location)

# Message boxes
pyautogui.alert('Task completed!')
response = pyautogui.confirm('Continue?', buttons=['Yes', 'No'])

Architecture

PyAutoGUI uses platform-specific implementations to provide a unified API:

  • Cross-platform core: Common API interface and failsafe mechanisms
  • Platform modules: Platform-specific implementations for Windows (Win32 API), macOS (Cocoa/Quartz), and Linux (X11)
  • Integration libraries: Uses PyScreeze for screenshots, PyMsgBox for dialogs, PyTweening for smooth animations, and PyGetWindow for window management
  • Failsafe system: Built-in protection against runaway automation by monitoring mouse position

Global Configuration

# Global pause between operations (seconds)
PAUSE: float = 0.1

# Failsafe mechanism - move mouse to corner to abort
FAILSAFE: bool = True

# Minimum duration for mouse movements
MINIMUM_DURATION: float = 0.1

# Screenshot logging for debugging
LOG_SCREENSHOTS: bool = False
LOG_SCREENSHOTS_LIMIT: int = 10

Exception Types

class PyAutoGUIException(Exception):
    """Base exception for PyAutoGUI errors"""

class FailSafeException(PyAutoGUIException):
    """Raised when failsafe mechanism is triggered"""

class ImageNotFoundException(PyAutoGUIException):
    """Raised when image cannot be found on screen"""

Capabilities

Mouse Control

Complete mouse automation including clicking, movement, dragging, and scrolling operations with smooth animations and configurable timing.

def click(x=None, y=None, clicks=1, interval=0.0, button='left', duration=0.0, tween=linear): ...
def moveTo(x, y, duration=0.0, tween=linear): ...
def dragTo(x, y, duration=0.0, tween=linear, button='left'): ...
def scroll(clicks, x=None, y=None): ...

Mouse Control

Keyboard Input

Comprehensive keyboard automation including key presses, text typing, and keyboard shortcuts with support for all standard keys and modifiers.

def press(keys, presses=1, interval=0.0): ...
def typewrite(message, interval=0.0): ...
def hotkey(*args): ...
def keyDown(key): ...
def keyUp(key): ...

Keyboard Input

Screen Capture and Image Recognition

Screenshot capture and computer vision capabilities for finding images, text, and UI elements on screen with pixel-perfect matching and tolerance controls.

def screenshot(imageFilename=None, region=None): ...
def locateOnScreen(image, **kwargs): ...
def locateAllOnScreen(image, **kwargs): ...
def pixel(x, y): ...
def pixelMatchesColor(x, y, expectedRGBColor, tolerance=0): ...

Screen and Image

Message Boxes

Cross-platform dialog boxes for user interaction including alerts, confirmations, text input, and password prompts.

def alert(text, title, button='OK'): ...
def confirm(text, title, buttons=['Cancel', 'OK']): ...
def prompt(text, title, default=''): ...
def password(text, title, default='', mask='*'): ...

Message Boxes

Window Management

Window control and management operations for finding, manipulating, and interacting with application windows (Windows platform only).

def getActiveWindow(): ...
def getWindowsWithTitle(title): ...
def getAllWindows(): ...
class Window: ...

Window Management

Utilities and Configuration

Helper functions for debugging, system information, timing controls, and animation easing functions.

def size(): ...
def position(): ...
def onScreen(x, y): ...
def displayMousePosition(): ...
def getInfo(): ...
def sleep(seconds): ...

Utilities

Common Types

from typing import Tuple, List, Optional, Union, Callable
from collections import namedtuple

# Coordinate and size types
Point = namedtuple('Point', ['x', 'y'])
Size = namedtuple('Size', ['width', 'height'])

# Color type (RGB tuple)
Color = Tuple[int, int, int]

# Region type (x, y, width, height)
Region = Tuple[int, int, int, int]

# Mouse button constants
LEFT: str = 'left'
RIGHT: str = 'right'
MIDDLE: str = 'middle'
PRIMARY: str = 'primary'
SECONDARY: str = 'secondary'

# Tween function type
TweenFunction = Callable[[float], float]