0
# PyAutoGUI
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: PyAutoGUI
7
- **Language**: Python
8
- **Installation**: `pip install pyautogui`
9
- **Version**: 0.9.54
10
- **Documentation**: https://pyautogui.readthedocs.org
11

12
## Core Imports
13

14
```python
15
import pyautogui
16
```
17

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

20
```python
21
# Common import pattern
22
import pyautogui
23

24
# Access all functions directly
25
pyautogui.click(100, 200)
26
pyautogui.typewrite('Hello World')
27
pyautogui.screenshot()
28
```
29

30
## Basic Usage
31

32
```python
33
import pyautogui
34
import time
35

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

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

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

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

54
# Screen capture and image recognition
55
screenshot = pyautogui.screenshot()
56
button_location = pyautogui.locateOnScreen('button.png')
57
if button_location:
58
    pyautogui.click(button_location)
59

60
# Message boxes
61
pyautogui.alert('Task completed!')
62
response = pyautogui.confirm('Continue?', buttons=['Yes', 'No'])
63
```
64

65
## Architecture
66

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

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

74
## Global Configuration
75

76
```python { .api }
77
# Global pause between operations (seconds)
78
PAUSE: float = 0.1
79

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

83
# Minimum duration for mouse movements
84
MINIMUM_DURATION: float = 0.1
85

86
# Screenshot logging for debugging
87
LOG_SCREENSHOTS: bool = False
88
LOG_SCREENSHOTS_LIMIT: int = 10
89
```
90

91
## Exception Types
92

93
```python { .api }
94
class PyAutoGUIException(Exception):
95
    """Base exception for PyAutoGUI errors"""
96

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

100
class ImageNotFoundException(PyAutoGUIException):
101
    """Raised when image cannot be found on screen"""
102
```
103

104
## Capabilities
105

106
### Mouse Control
107

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

110
```python { .api }
111
def click(x=None, y=None, clicks=1, interval=0.0, button='left', duration=0.0, tween=linear): ...
112
def moveTo(x, y, duration=0.0, tween=linear): ...
113
def dragTo(x, y, duration=0.0, tween=linear, button='left'): ...
114
def scroll(clicks, x=None, y=None): ...
115
```
116

117
[Mouse Control](./mouse-control.md)
118

119
### Keyboard Input
120

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

123
```python { .api }
124
def press(keys, presses=1, interval=0.0): ...
125
def typewrite(message, interval=0.0): ...
126
def hotkey(*args): ...
127
def keyDown(key): ...
128
def keyUp(key): ...
129
```
130

131
[Keyboard Input](./keyboard-input.md)
132

133
### Screen Capture and Image Recognition
134

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

137
```python { .api }
138
def screenshot(imageFilename=None, region=None): ...
139
def locateOnScreen(image, **kwargs): ...
140
def locateAllOnScreen(image, **kwargs): ...
141
def pixel(x, y): ...
142
def pixelMatchesColor(x, y, expectedRGBColor, tolerance=0): ...
143
```
144

145
[Screen and Image](./screen-image.md)
146

147
### Message Boxes
148

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

151
```python { .api }
152
def alert(text, title, button='OK'): ...
153
def confirm(text, title, buttons=['Cancel', 'OK']): ...
154
def prompt(text, title, default=''): ...
155
def password(text, title, default='', mask='*'): ...
156
```
157

158
[Message Boxes](./message-boxes.md)
159

160
### Window Management
161

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

164
```python { .api }
165
def getActiveWindow(): ...
166
def getWindowsWithTitle(title): ...
167
def getAllWindows(): ...
168
class Window: ...
169
```
170

171
[Window Management](./window-management.md)
172

173
### Utilities and Configuration
174

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

177
```python { .api }
178
def size(): ...
179
def position(): ...
180
def onScreen(x, y): ...
181
def displayMousePosition(): ...
182
def getInfo(): ...
183
def sleep(seconds): ...
184
```
185

186
[Utilities](./utilities.md)
187

188
## Common Types
189

190
```python { .api }
191
from typing import Tuple, List, Optional, Union, Callable
192
from collections import namedtuple
193

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

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

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

204
# Mouse button constants
205
LEFT: str = 'left'
206
RIGHT: str = 'right'
207
MIDDLE: str = 'middle'
208
PRIMARY: str = 'primary'
209
SECONDARY: str = 'secondary'
210

211
# Tween function type
212
TweenFunction = Callable[[float], float]
213
```