Skip to main content
Skip to content

PyAutoGUI Documentation Guide: Install, Examples and FAQ

PyAutoGUI in Python

PyAutoGUI is a Python library that controls the mouse and keyboard, takes screenshots and finds images on screen, so you can script almost any task you would normally do by hand. This guide covers the PyAutoGUI documentation you actually need: how to install it, the core commands, macOS permissions, image recognition, fixes for common errors, and answers to the questions people ask most.

What is PyAutoGUI?

PyAutoGUI is a lightweight Python library for automating GUI interactions. You can move the mouse, click, drag, scroll, type text, press keyboard shortcuts and capture the screen from a short script. It is available on PyPI and works on Windows, macOS and Linux.

People use it for filling in forms, repetitive desktop work, simple GUI testing and anything else where a human would otherwise click through the same steps again and again.

How to install PyAutoGUI

Open a terminal or command prompt and run:

pip install pyautogui

This downloads the library and its dependencies from PyPI. A few variations:

  • Windows 10 and 11: use the same command. Make sure Python and pip are on your PATH.
  • PyCharm: open Settings, go to the Python Interpreter page for your project, click the plus button, search for pyautogui and install it.
  • Install errors: upgrade pip first with pip install --upgrade pip, and use a virtual environment so dependencies stay isolated.

The official install page lists the extra packages needed on Linux.

PyAutoGUI documentation: where to find it

The official PyAutoGUI documentation is the reference for every function. The source code and issue tracker live in the PyAutoGUI GitHub repository, and the PyPI page shows the latest version and release notes. The docs are accurate but dense, so beginners do better starting with the examples below and then going to the docs for the details.

PyAutoGUI cheat sheet: mouse, keyboard and screen

Mouse

import pyautogui

pyautogui.size()                         # screen resolution
pyautogui.position()                     # current mouse position
pyautogui.moveTo(500, 400, duration=2)   # glide to x=500, y=400 over two seconds
pyautogui.move(0, 10)                    # move 10 pixels down from here
pyautogui.click()                        # left click at the current position
pyautogui.click(100, 200)                # move, then click
pyautogui.doubleClick()
pyautogui.rightClick()
pyautogui.dragTo(300, 300, duration=1, button='left')   # click and drag
pyautogui.scroll(200)                    # scroll up; negative values scroll down

Add duration and tween=pyautogui.easeInOutQuad to moveTo() when you want smoother, more human-looking movement.

Keyboard

pyautogui.write('Hello, world!', interval=0.1)   # type text
pyautogui.press('enter')                         # press one key
pyautogui.hotkey('ctrl', 's')                    # keyboard shortcut

pyautogui.keyDown('shift')                       # hold a key down
pyautogui.press(['4', '5', '6'])
pyautogui.keyUp('shift')

hotkey() works for any combination, such as Ctrl+C and Ctrl+V. Some shortcuts behave differently across applications and operating systems, so test each one in your target app.

Screenshots and image recognition

pyautogui.screenshot('my_screenshot.png')

button = pyautogui.locateOnScreen('button.png')
if button:
    pyautogui.click(pyautogui.center(button))

locateOnScreen() returns the position of an image on the screen, or nothing when it cannot find it.

What is PyAutoGUI used for?

PyAutoGUI Key Benefits

  • GUI testing: click and type through a desktop interface to check it behaves.
  • Data entry: fill forms or spreadsheets from a script.
  • Image recognition: find and click on-screen elements that have no accessible selector.
  • Repetitive tasks: rename files, submit forms, move data between applications.
  • Simple game automation: works for basic actions, though anti-cheat systems can flag it.

PyAutoGUI on macOS

PyAutoGUI works on macOS, but macOS blocks apps from controlling the computer until you allow it. Open System Settings (System Preferences on older versions), go to Privacy and Security, then Accessibility, and add the terminal or IDE you run Python from. Restart that terminal or IDE afterwards. Once permission is granted, the same script runs on macOS, Windows and Linux.

The fail-safe: how to stop a runaway script

PyAutoGUI has a built-in fail-safe that is on by default. Move the mouse to the top-left corner of the screen and PyAutoGUI raises an exception that stops the script. Leave it on while you develop, and add short pauses with pyautogui.PAUSE = 0.5 so you have time to react.

Troubleshooting common PyAutoGUI errors

  • Permission errors or nothing happens on macOS: grant Accessibility permission to your terminal or IDE and restart it.
  • Image not found: the screenshot must match what is on screen. Check display scaling and resolution, use a sharp crop of the target, and make sure the window is visible. Installing OpenCV lets you pass confidence=0.8 to tolerate small differences.
  • Cannot connect to display or display 0 errors: there is no graphical display. This happens over SSH, in containers and on CI servers. Run the script in a desktop session, or on Linux start a virtual display such as Xvfb.
  • Cannot import pyautogui: run pip list to confirm it is installed, and check that you are using the same Python environment that installed it.
  • write() types nothing or the wrong characters: make sure the target field has focus before typing, and check whether the application restricts special characters.
  • pip install fails: upgrade pip and use a current version of Python 3.

PyAutoGUI alternatives

PyAutoGUI is the simplest option when you need to drive a screen by coordinates or images. For other jobs, pick a more specific tool: Selenium for web browsers, AutoIt or pywinauto for Windows desktop applications, and Robot Framework when you want a full test automation tool with reporting. Compare them by what they can see: PyAutoGUI sees pixels, while the others can read the actual elements of an application.

PyAutoGUI FAQ

Is PyAutoGUI an API?

No. It is a Python library that wraps the operating system’s input and screen functions. It gives you programmatic control of the mouse and keyboard, but it is not a web or network API.

Does PyAutoGUI use AI?

No. PyAutoGUI itself has no machine learning. It can sit underneath an AI workflow, where a model decides what to do and PyAutoGUI performs the clicks and keystrokes.

Where do I download PyAutoGUI?

Install it with pip install pyautogui, which fetches it from PyPI. You can also download the source from the GitHub repository linked above.

What keyboard keys does PyAutoGUI support?

Most standard keys, including Shift, Ctrl, Alt, Enter, the arrow keys and F1 to F12. The documentation lists every valid key name for press() and hotkey().

Can PyAutoGUI work headless?

Not on its own, because it needs a real or virtual display. On Linux you can run it inside Xvfb. For browser work without a screen, a headless browser with Selenium or Playwright is a better fit.

Can games detect PyAutoGUI?

Yes, many anti-cheat systems detect automated input. Using it in online games can break the terms of service and get your account banned.

How do I take a screenshot with PyAutoGUI?

Call pyautogui.screenshot('file.png') to save the whole screen, or pass a region to capture part of it.

Why can’t PyAutoGUI find my image?

Usually the image does not match the screen: different resolution, display scaling, or a blurry crop. Take the reference image on the same machine and screen settings you will run on, and try the confidence option with OpenCV installed.

How do I scroll horizontally?

Use pyautogui.hscroll(200) to scroll right and a negative value to scroll left. Horizontal scrolling is not supported on every platform.

Is PyAutoGUI good for test automation?

It is fine for quick GUI checks and for apps that expose nothing else to automate. For regular regression testing, tools that read the interface elements directly are more reliable than coordinates and screenshots.

How do I automate a task with Python and PyAutoGUI?

Define what you want to automate, break it into small steps, write one function per step, then run the script and adjust the timing. Add pauses and image checks wherever a window might take time to appear.

Why do I get errors on macOS?

The most common cause is missing Accessibility permission. Grant it to your terminal or IDE, restart it, and make sure your Python version is current.

Want more testing guides in your Google results? Add Testmetry as a preferred source.

Share it :

Leave a Reply