pyautogui

A cross-platform GUI automation Python module for human beings. Used to programmatically control the mouse & keyboard.

10,278

1,243

10,278

533

View on GitHub

Top Related Projects

playwright-python

11,687

Python version of the Playwright testing and automation library.

awesome-test-automation

6,354

A curated list of awesome test automation frameworks, tools, libraries, and software for different programming languages. Sponsored by https://zapple.tech and https://automated-testing.info

robotframework

9,752

Generic automation framework for acceptance testing and RPA

selenium

30,518

A browser automation framework and ecosystem.

Quick Overview

PyAutoGUI is a cross-platform GUI automation Python module for human beings. It allows you to programmatically control the mouse and keyboard to automate interactions with other applications. PyAutoGUI works on Windows, macOS, and Linux, and can be used for tasks like filling out forms, clicking buttons, and taking screenshots.

Pros

Cross-platform compatibility (Windows, macOS, Linux)
Easy-to-use API for mouse and keyboard control
Includes functions for screenshot capture and image recognition
Extensive documentation and examples

Cons

May not work well with some applications, especially those with complex UIs
Can be affected by changes in screen resolution or UI layout
Potential for misuse if not implemented carefully
Limited support for more advanced GUI interactions

Code Examples

Moving the mouse and clicking:

import pyautogui

# Move the mouse to coordinates (100, 100) and click
pyautogui.moveTo(100, 100)
pyautogui.click()

Typing text:

import pyautogui

# Type a string with a 0.25 second delay between each character
pyautogui.write('Hello, World!', interval=0.25)

Taking a screenshot:

import pyautogui

# Take a screenshot of the entire screen and save it
screenshot = pyautogui.screenshot()
screenshot.save('screen.png')

Finding and clicking an image on the screen:

import pyautogui

# Locate an image on the screen and click it
location = pyautogui.locateOnScreen('button.png')
if location:
    pyautogui.click(location)
else:
    print("Image not found on screen")

Getting Started

To get started with PyAutoGUI, first install it using pip:

pip install pyautogui

Then, you can import it in your Python script:

import pyautogui

# Enable fail-safe (move mouse to upper-left corner to abort)
pyautogui.FAILSAFE = True

# Get the screen size
screen_width, screen_height = pyautogui.size()

# Move the mouse to the center of the screen
pyautogui.moveTo(screen_width / 2, screen_height / 2)

# Perform a left click
pyautogui.click()

This example moves the mouse to the center of the screen and performs a left click. Remember to use PyAutoGUI responsibly and be aware of its limitations and potential risks when automating GUI interactions.

Competitor Comparisons

playwright-python

11,687

Python version of the Playwright testing and automation library.

Pros of Playwright-Python

Cross-browser support (Chromium, Firefox, WebKit)
Powerful automation capabilities for modern web applications
Built-in waiting mechanisms and auto-waits for elements

Cons of Playwright-Python

Steeper learning curve for beginners
Focused on web automation, less suitable for general desktop automation
Requires more setup and dependencies

Code Comparison

Playwright-Python:

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch()
    page = browser.new_page()
    page.goto("https://example.com")
    page.click("button#submit")

PyAutoGUI:

import pyautogui

pyautogui.click(100, 200)
pyautogui.typewrite("Hello, world!")
pyautogui.press("enter")

Summary

Playwright-Python excels in web automation with cross-browser support and powerful features for modern web applications. It's ideal for complex web testing and automation scenarios. PyAutoGUI, on the other hand, is simpler to use and more versatile for general desktop automation tasks, including non-web applications. The choice between the two depends on the specific automation needs and the target environment.

RPA-Python

4,899

Python package for doing RPA

Pros of RPA-Python

More comprehensive RPA toolkit with additional features beyond GUI automation
Includes web automation capabilities using Selenium
Offers a higher-level abstraction for complex RPA tasks

Cons of RPA-Python

Less actively maintained compared to PyAutoGUI
Steeper learning curve due to more complex API
Limited documentation and community support

Code Comparison

PyAutoGUI example:

import pyautogui

pyautogui.moveTo(100, 100)
pyautogui.click()
pyautogui.typewrite('Hello, world!')

RPA-Python example:

import rpa as r

r.init()
r.click('button.png')
r.type('Hello, world!')
r.close()

Both libraries offer similar basic functionality for GUI automation, but RPA-Python provides a more abstracted approach with additional features for web automation and complex RPA tasks. PyAutoGUI is more focused on simple GUI interactions and has a larger user base with better documentation. RPA-Python might be preferred for more complex RPA projects, while PyAutoGUI is better suited for simpler automation tasks and has a gentler learning curve.

awesome-test-automation

6,354

A curated list of awesome test automation frameworks, tools, libraries, and software for different programming languages. Sponsored by https://zapple.tech and https://automated-testing.info

Pros of awesome-test-automation

Comprehensive resource for various test automation tools and frameworks
Covers multiple programming languages and platforms
Community-driven with regular updates and contributions

Cons of awesome-test-automation

Not a standalone tool or library, but a curated list of resources
Requires additional effort to implement specific tools or frameworks
May overwhelm beginners with the vast amount of information

Code comparison

While a direct code comparison isn't applicable due to the nature of the repositories, here's a brief example of how they differ in usage:

awesome-test-automation (example of accessing a resource):

## Python test automation

* [Python test automation resources](https://github.com/atinfo/awesome-test-automation/blob/master/python-test-automation.md)

PyAutoGUI (example of automating mouse movement):

import pyautogui

pyautogui.moveTo(100, 100, duration=2)
pyautogui.click()

PyAutoGUI is a specific library for GUI automation, while awesome-test-automation is a curated list of various testing resources, including GUI automation tools. PyAutoGUI offers direct functionality, whereas awesome-test-automation provides a comprehensive overview of available tools and frameworks for test automation across different languages and platforms.

robotframework

9,752

Generic automation framework for acceptance testing and RPA

Pros of Robot Framework

More comprehensive test automation framework with support for various testing types (acceptance, integration, etc.)
Keyword-driven approach allows for creating reusable test cases and libraries
Extensive ecosystem with many built-in and external libraries for different testing needs

Cons of Robot Framework

Steeper learning curve due to its domain-specific language and syntax
Less suitable for quick, simple automation tasks compared to PyAutoGUI
Requires more setup and configuration for basic usage

Code Comparison

Robot Framework:

*** Settings ***
Library    SeleniumLibrary

*** Test Cases ***
Open Browser and Search
    Open Browser    https://www.google.com    chrome
    Input Text    name=q    Robot Framework
    Submit Form
    Page Should Contain    Robot Framework

PyAutoGUI:

import pyautogui

pyautogui.PAUSE = 1
pyautogui.hotkey('win', 'r')
pyautogui.write('https://www.google.com')
pyautogui.press('enter')
pyautogui.write('PyAutoGUI')
pyautogui.press('enter')

The code comparison shows that Robot Framework is more verbose and structured, focusing on web automation, while PyAutoGUI offers a simpler approach for general GUI automation tasks.

selenium

30,518

A browser automation framework and ecosystem.

Pros of Selenium

Designed specifically for web automation and testing
Supports multiple programming languages (not just Python)
Interacts directly with web elements, providing more reliable automation for web-based tasks

Cons of Selenium

Steeper learning curve compared to PyAutoGUI
Requires browser drivers and more setup
Limited to web-based automation; cannot interact with desktop applications

Code Comparison

PyAutoGUI:

import pyautogui

pyautogui.click(100, 200)
pyautogui.typewrite('Hello, world!')
pyautogui.press('enter')

Selenium:

from selenium import webdriver
from selenium.webdriver.common.keys import Keys

driver = webdriver.Chrome()
driver.get("https://example.com")
element = driver.find_element_by_name("q")
element.send_keys("Hello, world!" + Keys.RETURN)

PyAutoGUI is simpler for general desktop automation, using screen coordinates and simulating mouse/keyboard inputs. Selenium is more complex but offers powerful web-specific automation, interacting directly with web elements using locators and providing better support for dynamic web content.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

PyAutoGUI

PyAutoGUI is a cross-platform GUI automation Python module for human beings. Used to programmatically control the mouse & keyboard.

pip install pyautogui

Full documentation available at https://pyautogui.readthedocs.org

Simplified Chinese documentation available at https://github.com/asweigart/pyautogui/blob/master/docs/simplified-chinese.ipynb

Source code available at https://github.com/asweigart/pyautogui

If you need help installing Python, visit https://installpython3.com/

Dependencies

PyAutoGUI supports Python 2 and 3. If you are installing PyAutoGUI from PyPI using pip:

Windows has no dependencies. The Win32 extensions do not need to be installed.

macOS needs the pyobjc-core and pyobjc module installed (in that order).

Linux needs the python3-xlib (or python-xlib for Python 2) module installed.

Pillow needs to be installed, and on Linux you may need to install additional libraries to make sure Pillow's PNG/JPEG works correctly. See:

https://stackoverflow.com/questions/7648200/pip-install-pil-e-tickets-1-no-jpeg-png-support

http://ubuntuforums.org/showthread.php?t=1751455

If you want to do development and contribute to PyAutoGUI, you will need to install these modules from PyPI:

pyscreeze
pymsgbox
pytweening

Example Usage

Keyboard and Mouse Control

The x, y coordinates used by PyAutoGUI has the 0, 0 origin coordinates in the top left corner of the screen. The x coordinates increase going to the right (just as in mathematics) but the y coordinates increase going down (the opposite of mathematics). On a screen that is 1920 x 1080 pixels in size, coordinates 0, 0 are for the top left while 1919, 1079 is for the bottom right.

Currently, PyAutoGUI only works on the primary monitor. PyAutoGUI isn't reliable for the screen of a second monitor (the mouse functions may or may not work on multi-monitor setups depending on your operating system and version).

All keyboard presses done by PyAutoGUI are sent to the window that currently has focus, as if you had pressed the physical keyboard key.

    >>> import pyautogui
    >>> screenWidth, screenHeight = pyautogui.size() # Returns two integers, the width and height of the screen. (The primary monitor, in multi-monitor setups.)
    >>> currentMouseX, currentMouseY = pyautogui.position() # Returns two integers, the x and y of the mouse cursor's current position.
    >>> pyautogui.moveTo(100, 150) # Move the mouse to the x, y coordinates 100, 150.
    >>> pyautogui.click() # Click the mouse at its current location.
    >>> pyautogui.click(200, 220) # Click the mouse at the x, y coordinates 200, 220.
    >>> pyautogui.move(None, 10)  # Move mouse 10 pixels down, that is, move the mouse relative to its current position.
    >>> pyautogui.doubleClick() # Double click the mouse at the
    >>> pyautogui.moveTo(500, 500, duration=2, tween=pyautogui.easeInOutQuad) # Use tweening/easing function to move mouse over 2 seconds.
    >>> pyautogui.write('Hello world!', interval=0.25)  # Type with quarter-second pause in between each key.
    >>> pyautogui.press('esc') # Simulate pressing the Escape key.
    >>> pyautogui.keyDown('shift')
    >>> pyautogui.write(['left', 'left', 'left', 'left', 'left', 'left'])
    >>> pyautogui.keyUp('shift')
    >>> pyautogui.hotkey('ctrl', 'c')

Display Message Boxes

    >>> import pyautogui
    >>> pyautogui.alert('This is an alert box.')
    'OK'
    >>> pyautogui.confirm('Shall I proceed?')
    'Cancel'
    >>> pyautogui.confirm('Enter option.', buttons=['A', 'B', 'C'])
    'B'
    >>> pyautogui.prompt('What is your name?')
    'Al'
    >>> pyautogui.password('Enter password (text will be hidden)')
    'swordfish'

Screenshot Functions

(PyAutoGUI uses Pillow for image-related features.)

    >>> import pyautogui
    >>> im1 = pyautogui.screenshot()
    >>> im1.save('my_screenshot.png')
    >>> im2 = pyautogui.screenshot('my_screenshot2.png')

You can also locate where an image is on the screen:

    >>> import pyautogui
    >>> button7location = pyautogui.locateOnScreen('button.png') # returns (left, top, width, height) of matching region
    >>> button7location
    (1416, 562, 50, 41)
    >>> buttonx, buttony = pyautogui.center(button7location)
    >>> buttonx, buttony
    (1441, 582)
    >>> pyautogui.click(buttonx, buttony)  # clicks the center of where the button was found

The locateCenterOnScreen() function returns the center of this match region:

    >>> import pyautogui
    >>> buttonx, buttony = pyautogui.locateCenterOnScreen('button.png') # returns (x, y) of matching region
    >>> buttonx, buttony
    (1441, 582)
    >>> pyautogui.click(buttonx, buttony)  # clicks the center of where the button was found

How Does PyAutoGUI Work?

The three major operating systems (Windows, macOS, and Linux) each have different ways to programmatically control the mouse and keyboard. This can often involve confusing, obscure, and deeply technical details. The job of PyAutoGUI is to hide all of this complexity behind a simple API.

On Windows, PyAutoGUI accesses the Windows API (also called the WinAPI or win32 API) through the built-in ctypes module. The nicewin module at https://github.com/asweigart/nicewin provides a demonstration for how Windows API calls can be made through Python.
On macOS, PyAutoGUI uses the rubicon-objc module to access the Cocoa API.
On Linux, PyAutoGUI uses the Xlib module to access the X11 or X Window System.

Support

If you find this project helpful and would like to support its development, consider donating to its creator on Patreon.

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot