How to Take Screenshots in Python with PyAutoGUI
Capture and save your screen with PyAutoGUI, crop a region, handle platform setup, and troubleshoot common screenshot problems.
Use pyautogui.screenshot() to capture the primary display in Python. Pass a filename to save the image immediately, or save the returned Pillow image later. To capture a rectangle, pass region=(left, top, width, height).
import pyautogui
# Capture the full primary screen and save it as a PNG.
image = pyautogui.screenshot("screenshot.png")
# Capture a rectangle: left, top, width, height.
region_image = pyautogui.screenshot(region=(0, 0, 300, 400))
region_image.save("region.png")PyAutoGUI documents support for Windows, macOS, and Linux. Its screenshot function returns a Pillow image object, so you can also inspect or transform the image before saving it. See the screenshot reference, installation guide, and quickstart.
1. Install PyAutoGUI and screenshot dependencies
Install PyAutoGUI in the same Python environment that will run your script. The official installation guide gives these commands:
# macOS and Linux
python3 -m pip install pyautogui
# Windows
py -m pip install pyautoguiPyAutoGUI’s screenshot documentation also identifies Pillow as a requirement. The installation guide lists scrot, python3-tk, and python3-dev among the Linux packages; the screenshot reference calls out the scrot command on Linux and the built-in screencapture command on macOS. Package availability and setup can vary by operating system version, so check the current environment if capture fails after installing the Python package.
2. Capture and save the full screen
Pass an output filename to save during capture:
import pyautogui
image = pyautogui.screenshot("screenshot.png")
print(image.size) # (width, height)The call both writes the image and returns it as a Pillow image object. If you want to choose the output path or format later, capture first and call save():
from pathlib import Path
import pyautogui
image = pyautogui.screenshot()
output_path = Path("captures") / "screen.png"
output_path.parent.mkdir(parents=True, exist_ok=True)
image.save(output_path)Use a filename extension that matches the intended image format in ordinary workflows, such as .png. Saving explicitly also makes it easy to create the destination directory first, as in the example.
3. Capture only a rectangular region
Use the region argument to limit the screenshot. Its values are (left, top, width, height), measured from the primary display’s top-left coordinate, rather than left, top, right, bottom.
import pyautogui
left = 120
top = 80
width = 640
height = 400
image = pyautogui.screenshot(region=(left, top, width, height))
image.save("region.png")Choose coordinates and dimensions that fit the display. A region is a rectangular screen crop; this API reference does not describe selecting a screenshot by application window name.
4. Choose the right save pattern
| Pattern | Use it when |
|---|---|
pyautogui.screenshot("file.png") |
You want a short capture-and-save operation. |
image = pyautogui.screenshot(); image.save(...) |
You need to inspect, transform, or decide where to save the returned Pillow image. |
pyautogui.screenshot(region=(...)) |
You want a rectangular part of the primary display. |
5. Runnable script with basic error reporting
This script captures a full-screen image, creates the output folder, saves the result, and reports common setup failures with a useful next step.
from pathlib import Path
import sys
try:
import pyautogui
except ImportError:
sys.exit("PyAutoGUI is not installed in this Python environment. Install it with python3 -m pip install pyautogui (or py -m pip install pyautogui on Windows).")
output_path = Path("captures") / "screenshot.png"
output_path.parent.mkdir(parents=True, exist_ok=True)
try:
image = pyautogui.screenshot()
image.save(output_path)
except Exception as error:
sys.exit(f"Screenshot capture or save failed: {error}")
print(f"Saved {image.width}x{image.height} screenshot to {output_path.resolve()}")6. Platform and display considerations
Windows, macOS, and Linux
The PyAutoGUI quickstart describes the library as supporting Windows, macOS, and Linux. Platform screenshot facilities still matter: its screenshot documentation identifies Pillow as required, and calls out scrot on Linux and screencapture on macOS. On Linux, the installation guide additionally lists python3-tk and python3-dev. If you use a virtual environment, install PyAutoGUI there and run the script with that same interpreter.
Primary monitor
The PyAutoGUI FAQ says screenshots currently handle only the primary monitor. If the content is on another display, verify the behavior in your actual environment before relying on the image. The documented call does not offer a monitor selector.
Permissions and session context
Desktop capture runs in the environment where the Python process executes. A script launched in a remote shell, container, service account, or headless session may not have access to the interactive desktop. Run it in a session with an available display and the required operating-system screenshot facilities. On systems that restrict screen capture, review the platform’s permissions for the application running Python.
7. Troubleshooting
| Symptom | Likely cause | What to do |
|---|---|---|
ModuleNotFoundError: No module named 'pyautogui' |
PyAutoGUI was installed into a different Python environment. | Install using the interpreter that runs the script: python3 -m pip install pyautogui or py -m pip install pyautogui on Windows. |
| Screenshot dependency or backend error | Pillow or a platform screenshot facility is unavailable. | Confirm Pillow is installed in the active environment. On Linux, check the documented scrot, python3-tk, and python3-dev packages; on macOS, confirm the screenshot facility is available. |
| Capture is blank or unavailable in a server/container | The process may not have an interactive desktop or display access. | Run the script in a desktop session with capture access, or use a browser screenshot service for web pages instead of trying to capture a nonexistent desktop. |
| Wrong portion of the screen appears | The region tuple may use the wrong order or coordinates. | Pass (left, top, width, height); width and height are sizes, not right and bottom coordinates. |
| Screenshot omits another monitor | The documented FAQ says only the primary monitor is currently handled. | Place the target content on the primary monitor or verify a different capture approach in your setup. |
| File was not created | The parent directory may not exist or the path may not be writable. | Create the directory first, use an absolute path to check where the file should go, and ensure the process has write permission. |
8. Performance, reliability, and cost
PyAutoGUI’s screenshot reference gives roughly 100 milliseconds for a 1920×1080 screenshot as an approximate example. Treat that as documentation guidance, not a promise: capture time can vary with display size, operating system, machine, and environment. Larger images also take more storage and time to write.
For reliability, use an explicit output path, ensure its directory exists, and handle capture and file errors. If a capture is part of a repeated workflow, confirm that the Python process remains attached to the intended desktop session and that the target display is the primary monitor.
PyAutoGUI is a Python package; its documentation does not specify a per-screenshot service charge. Account for your own environment and storage. For a web page, a local desktop screenshot is often the wrong tool: a browser capture API can render a URL without requiring a desktop session.
Or skip the browser setup
PyAutoGUI captures the desktop where Python runs. For a website URL, ScreenshotNeo is a website screenshot API and MCP server: one GET request returns a PNG, JPEG, WebP, or PDF. Its API documentation has the request options.
import requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
timeout=90,
)
open("shot.webp", "wb").write(r.content)ScreenshotNeo accepts cookie banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers identify the page verdict and billing status. Its MCP server gives AI agents tools to take screenshots, get page information, and capture PDFs. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots.
Sign up free for 1,000 screenshots a month, no card required.
FAQ
Does PyAutoGUI return an image or only write a file?
It returns a Pillow image object. Supplying a filename saves it and still returns the image.
Can I capture a specific application window?
The cited screenshot reference documents full-screen capture and rectangular regions, not a window-targeted capture argument.
Can I use PyAutoGUI to screenshot a website on a server?
Only if the process has a usable desktop session to capture. For a URL rendered in a browser without a desktop session, use a browser screenshot API such as ScreenshotNeo.
