Cheat Sheet¶
This is a quickstart reference to using PyAutoGUI. PyAutoGUI is cross-platform GUI automation module that works on Python 2 & 3. You can control the mouse and keyboard as well as perform basic image recognition to automate tasks on your computer.
All the keyword arguments in the examples on this page are optional.
PyAutoGUI works on Windows/Mac/Linux and on Python 2 & 3. Install from PyPI with pip install pyautogui .
General Functions¶
>>> pyautogui.position() # current mouse x and y (968, 56) >>> pyautogui.size() # current screen resolution width and height (1920, 1080) >>> pyautogui.onScreen(x, y) # True if x & y are within the screen. True
Fail-Safes¶
Set up a 2.5 second pause after each PyAutoGUI call:
>>> import pyautogui >>> pyautogui.PAUSE = 2.5
When fail-safe mode is True , moving the mouse to the upper-left will raise a pyautogui.FailSafeException that can abort your program:
>>> import pyautogui >>> pyautogui.FAILSAFE = True
Mouse Functions¶
XY coordinates have 0, 0 origin at top left corner of the screen. X increases going right, Y increases going down.
>>> pyautogui.moveTo(x, y, duration=num_seconds) # move mouse to XY coordinates over num_second seconds >>> pyautogui.moveRel(xOffset, yOffset, duration=num_seconds) # move mouse relative to its current position
If duration is 0 or unspecified, movement is immediate. Note: dragging on Mac can’t be immediate.
>>> pyautogui.dragTo(x, y, duration=num_seconds) # drag mouse to XY >>> pyautogui.dragRel(xOffset, yOffset, duration=num_seconds) # drag mouse relative to its current position
Calling click() just clicks the mouse once with the left button at the mouse’s current location, but the keyword arguments can change that:
>>> pyautogui.click(x=moveToX, y=moveToY, clicks=num_of_clicks, interval=secs_between_clicks, button='left')
The button keyword argument can be ‘left’ , ‘middle’ , or ‘right’ .
All clicks can be done with click() , but these functions exist for readability. Keyword args are optional:
>>> pyautogui.rightClick(x=moveToX, y=moveToY) >>> pyautogui.middleClick(x=moveToX, y=moveToY) >>> pyautogui.doubleClick(x=moveToX, y=moveToY) >>> pyautogui.tripleClick(x=moveToX, y=moveToY)
Positive scrolling will scroll up, negative scrolling will scroll down:
>>> pyautogui.scroll(amount_to_scroll, x=moveToX, y=moveToY)
Individual button down and up events can be called separately:
>>> pyautogui.mouseDown(x=moveToX, y=moveToY, button='left') >>> pyautogui.mouseUp(x=moveToX, y=moveToY, button='left')
Keyboard Functions¶
Key presses go to wherever the keyboard cursor is at function-calling time.
>>> pyautogui.typewrite('Hello world!\n', interval=secs_between_keys) # useful for entering text, newline is Enter
A list of key names can be passed too:
>>> pyautogui.typewrite(['a', 'b', 'c', 'left', 'backspace', 'enter', 'f1'], interval=secs_between_keys)
The full list of key names is in pyautogui.KEYBOARD_KEYS .
Keyboard hotkeys like Ctrl-S or Ctrl-Shift-1 can be done by passing a list of key names to hotkey() :
>>> pyautogui.hotkey('ctrl', 'c') # ctrl-c to copy >>> pyautogui.hotkey('ctrl', 'v') # ctrl-v to paste
Individual button down and up events can be called separately:
>>> pyautogui.keyDown(key_name) >>> pyautogui.keyUp(key_name)
Message Box Functions¶
If you need to pause the program until the user clicks OK on something, or want to display some information to the user, the message box functions have similar names that JavaScript has:
>>> pyautogui.alert('This displays some text with an OK button.') >>> pyautogui.confirm('This displays text and has an OK and Cancel button.') 'OK' >>> pyautogui.prompt('This lets the user type in a string and press OK.') 'This is what I typed in.'
The prompt() function will return None if the user clicked Cancel.
Screenshot Functions¶
PyAutoGUI uses Pillow/PIL for its image-related data.
On Linux, you must run sudo apt-get install scrot to use the screenshot features.
>>> pyautogui.screenshot() # returns a Pillow/PIL Image object >>> pyautogui.screenshot(‘foo.png’) # returns a Pillow/PIL Image object, and saves it to a file
If you have an image file of something you want to click on, you can find it on the screen with locateOnScreen() .
>>> pyautogui.locateOnScreen('looksLikeThis.png') # returns (left, top, width, height) of first place it is found (863, 417, 70, 13)
The locateAllOnScreen() function will return a generator for all the locations it is found on the screen:
>>> for i in pyautogui.locateAllOnScreen('looksLikeThis.png') . . (863, 117, 70, 13) (623, 137, 70, 13) (853, 577, 70, 13) (883, 617, 70, 13) (973, 657, 70, 13) (933, 877, 70, 13)
>>> list(pyautogui.locateAllOnScreen('looksLikeThis.png')) [(863, 117, 70, 13), (623, 137, 70, 13), (853, 577, 70, 13), (883, 617, 70, 13), (973, 657, 70, 13), (933, 877, 70, 13)]
The locateCenterOnScreen() function just returns the XY coordinates of the middle of where the image is found on the screen:
>>> pyautogui.locateCenterOnScreen('looksLikeThis.png') # returns center x and y (898, 423)
These functions return None if the image couldn’t be found on the screen.
Note: The locate functions are slow and can take a full second or two.
© Copyright 2019, Al Sweigart Revision 24d638dc .
Versions latest Downloads pdf html epub On Read the Docs Project Home Builds Free document hosting provided by Read the Docs.
Keyboard Control Functions¶
The primary keyboard function is write() . This function will type the characters in the string that is passed. To add a delay interval in between pressing each character key, pass an int or float for the interval keyword argument.
>>> pyautogui.write('Hello world!') # prints out "Hello world!" instantly >>> pyautogui.write('Hello world!', interval=0.25) # prints out "Hello world!" with a quarter second delay after each character
You can only press single-character keys with write() , so you can’t press the Shift or F1 keys, for example.
The press(), keyDown(), and keyUp() Functions¶
To press these keys, call the press() function and pass it a string from the pyautogui.KEYBOARD_KEYS such as enter , esc , f1 . See KEYBOARD_KEYS.
>>> pyautogui.press('enter') # press the Enter key >>> pyautogui.press('f1') # press the F1 key >>> pyautogui.press('left') # press the left arrow key
The press() function is really just a wrapper for the keyDown() and keyUp() functions, which simulate pressing a key down and then releasing it up. These functions can be called by themselves. For example, to press the left arrow key three times while holding down the Shift key, call the following:
>>> pyautogui.keyDown('shift') # hold down the shift key >>> pyautogui.press('left') # press the left arrow key >>> pyautogui.press('left') # press the left arrow key >>> pyautogui.press('left') # press the left arrow key >>> pyautogui.keyUp('shift') # release the shift key
To press multiple keys similar to what write() does, pass a list of strings to press() . For example:
>>> pyautogui.press(['left', 'left', 'left'])
Or you can set how many presses left :
>>> pyautogui.press('left', presses=3)
To add a delay interval in between each press, pass an int or float for the interval keyword argument.
The hold() Context Manager¶
To make holding a key convenient, the hold() function can be used as a context manager and passed a string from the pyautogui.KEYBOARD_KEYS such as shift , ctrl , alt , and this key will be held for the duration of the with context block. See KEYBOARD_KEYS.
>>> with pyautogui.hold('shift'): pyautogui.press(['left', 'left', 'left'])
…is equivalent to this code:
>>> pyautogui.keyDown('shift') # hold down the shift key >>> pyautogui.press('left') # press the left arrow key >>> pyautogui.press('left') # press the left arrow key >>> pyautogui.press('left') # press the left arrow key >>> pyautogui.keyUp('shift') # release the shift key
The hotkey() Function¶
To make pressing hotkeys or keyboard shortcuts convenient, the hotkey() can be passed several key strings which will be pressed down in order, and then released in reverse order. This code:
>>> pyautogui.hotkey('ctrl', 'shift', 'esc')
…is equivalent to this code:
>>> pyautogui.keyDown('ctrl') >>> pyautogui.keyDown('shift') >>> pyautogui.keyDown('esc') >>> pyautogui.keyUp('esc') >>> pyautogui.keyUp('shift') >>> pyautogui.keyUp('ctrl')
To add a delay interval in between each press, pass an int or float for the interval keyword argument.
KEYBOARD_KEYS¶
The following are the valid strings to pass to the press() , keyDown() , keyUp() , and hotkey() functions:
['\t', '\n', '\r', ' ', '!', '"', '#', '$', '%', '&', "'", '(', ')', '*', '+', ',', '-', '.', '/', '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', ':', ';', ', '=', '>', '?', '@', '[', '\\', ']', '^', '_', '`', 'a', 'b', 'c', 'd', 'e','f', 'g', 'h', 'i', 'j', 'k', 'l', 'm', 'n', 'o', 'p', 'q', 'r', 's', 't', 'u', 'v', 'w', 'x', 'y', 'z', ', '|', '>', '~', 'accept', 'add', 'alt', 'altleft', 'altright', 'apps', 'backspace', 'browserback', 'browserfavorites', 'browserforward', 'browserhome', 'browserrefresh', 'browsersearch', 'browserstop', 'capslock', 'clear', 'convert', 'ctrl', 'ctrlleft', 'ctrlright', 'decimal', 'del', 'delete', 'divide', 'down', 'end', 'enter', 'esc', 'escape', 'execute', 'f1', 'f10', 'f11', 'f12', 'f13', 'f14', 'f15', 'f16', 'f17', 'f18', 'f19', 'f2', 'f20', 'f21', 'f22', 'f23', 'f24', 'f3', 'f4', 'f5', 'f6', 'f7', 'f8', 'f9', 'final', 'fn', 'hanguel', 'hangul', 'hanja', 'help', 'home', 'insert', 'junja', 'kana', 'kanji', 'launchapp1', 'launchapp2', 'launchmail', 'launchmediaselect', 'left', 'modechange', 'multiply', 'nexttrack', 'nonconvert', 'num0', 'num1', 'num2', 'num3', 'num4', 'num5', 'num6', 'num7', 'num8', 'num9', 'numlock', 'pagedown', 'pageup', 'pause', 'pgdn', 'pgup', 'playpause', 'prevtrack', 'print', 'printscreen', 'prntscrn', 'prtsc', 'prtscr', 'return', 'right', 'scrolllock', 'select', 'separator', 'shift', 'shiftleft', 'shiftright', 'sleep', 'space', 'stop', 'subtract', 'tab', 'up', 'volumedown', 'volumemute', 'volumeup', 'win', 'winleft', 'winright', 'yen', 'command', 'option', 'optionleft', 'optionright']
© Copyright 2019, Al Sweigart Revision 24d638dc .
Versions latest Downloads pdf html epub On Read the Docs Project Home Builds Free document hosting provided by Read the Docs.