PyAutoGUI is usually working when a macOS screenshot contains only the wallpaper and menu bar. That image is the expected privacy-filtered result when the process running Python has not been approved in Screen & System Audio Recording. Grant that permission to the actual host application (Terminal, iTerm, an IDE, notebook app, or packaged Python app), fully quit and relaunch it, and then test a full-screen capture before troubleshooting regions or image matching.
Why PyAutoGUI shows the wallpaper instead of your windows
On macOS Catalina and later, screen contents belonging to other applications are protected by a privacy control. PyAutoGUI’s screenshot path uses PyScreeze and Pillow; on macOS, the documented backend invokes Apple’s built-in screencapture command. If the calling process lacks Screen Recording approval, macOS can still return a valid-looking image containing the desktop background and menu bar while withholding pixels from Finder, browsers, editors, and other apps.
Apple describes the same behavior for Core Graphics capture: an unauthorized request for another application’s window can return no image, while an app can still capture its own windows, the menu bar, and the desktop background. A wallpaper-only PNG therefore points to a permission or process-identity problem, not automatically to a broken PyAutoGUI installation.
Fix it in the correct order
- Close the process that is running Python. Quit Terminal, iTerm, your IDE, notebook application and any packaged app that launched the script. Closing only the script is not enough if the host process keeps the old authorization state.
- Open the recording permission panel. Choose Apple menu > System Settings > Privacy & Security > Screen & System Audio Recording. This panel controls which applications may record the screen and audio and includes an Add button for applications that are not listed.
- Enable the real host application. Turn on the entry that actually executes Python: for example, Terminal, iTerm, Visual Studio Code, PyCharm, Jupyter, or the packaged Python application. Enabling a shell or launcher does not authorize a different process that owns the capture call.
- Accept the macOS prompt if it appears. The first failed Core Graphics capture may trigger an authorization dialog, but macOS does not guarantee that the dialog will appear on every attempt. Use the Settings panel rather than waiting for a prompt.
- Quit and relaunch the host. Return to the same Terminal, IDE, or notebook that you enabled. Permission changes are most reliable when tested by a fresh process.
- Run a minimal full-screen test. Do not begin with a selector, coordinate region, or image-matching call. Use the smallest command that proves whether application pixels are available:
python3 -c "import pyautogui; im=pyautogui.screenshot('/tmp/pyautogui-test.png'); print(im.size)"
open /tmp/pyautogui-test.pngThe command should print the display dimensions and open an image that includes ordinary application windows. If it does, the capture path is authorized. Only then move on to a region or locateOnScreen().
#1 Best Overall
- AN AMAZING MAC AT A SURPRISING PRICE — With an incredibly portable and durable aluminum design, up to 16 hours of battery life,* and the A18 Pro chip, MacBook Neo is ready to go wherever school takes you.
- FOUR STUNNING COLORS. ONE DURABLE DESIGN — Choose from four beautiful colors — Silver, Blush, Citrus, or Indigo — each with a color-coordinated keyboard. And MacBook Neo is made with a durable recycled aluminum enclosure that helps it reach 60 percent recycled content by weight — the most ever in any Apple product.*
- FLY THROUGH EVERYDAY ASSIGNMENTS — Whether you’re cramming for finals, using Apple Intelligence* to summarize class notes, creating presentations, or even playing the latest Apple Arcade game,* MacBook Neo delivers the performance and AI capabilities you need to get things done.
- UP TO 16 HOURS OF BATTERY LIFE — MacBook Neo delivers all day battery life, so you can power through from early morning classes to late night study sessions without worrying about plugging in.
- A VIBRANT 13-INCH DISPLAY* — The gorgeous Liquid Retina display on MacBook Neo supports 1 billion colors, so photos and videos pop and text is crisp for easy reading.
Understand the permission boundary
Screen recording is not the same as input control
Screen & System Audio Recording authorizes reading pixels. Accessibility and Input Monitoring are separate macOS privacy categories. They can be needed for PyAutoGUI actions such as clicking, typing, or observing input, but enabling them does not grant screen-capture access. If screenshots are wallpaper-only, fix Screen Recording first; add the other permissions only when an automation action reports its own denial.
A region cannot bypass privacy filtering
PyAutoGUI accepts a rectangle in the form region=(left, top, width, height). The region limits how much of the already-authorized display is requested; it cannot reveal an unauthorized window. Prove full-screen capture first, then reduce the area:
import pyautogui
image = pyautogui.screenshot(region=(0, 0, 1200, 800))
image.save("region.png")Protected application content can be a separate issue
Test with Finder or another ordinary window. Some applications deliberately restrict capture of their own content. One protected window remaining blank does not establish that PyAutoGUI is failing if other windows are visible in the same screenshot.
When permission appears enabled but the image is still wallpaper-only
Verify process identity
Run the minimal command from the exact host whose entry is enabled. An IDE may launch a helper, interpreter, or bundled application; a notebook kernel may outlive the notebook UI; a packaged app has its own identity. Test separately from Terminal and from the IDE. If one works and the other does not, authorize the failing host rather than changing PyAutoGUI code.
Free tools Windows power users keep installed
One-click scans. No signup required.
Rank #2
- BUILT FOR COLLEGE. AND BEYOND — MacBook Air with the M5 chip packs blazing speed and powerful AI capabilities into an incredibly portable design. And with up to 18 hours of battery life,* this thin and light powerhouse is ready to take on almost any major, just about anywhere.
- TEAR THROUGH TOUGH ASSIGNMENTS — With its faster CPU and unified memory, the M5 chip delivers even more performance and fluidity across apps, making multitasking and creative workflows smooth and responsive. A powerful Neural Engine and next-generation GPU with Neural Accelerators give you a powerful platform for AI.
- MAKE QUICK WORK OF YOUR TO-DO LIST — Apple Intelligence helps you write, express yourself, and get things done effortlessly — whether it’s for school or everyday life. With groundbreaking privacy protections, it gives you peace of mind that no one else can access your data — not even Apple.*
- UP TO 18 HOURS OF BATTERY LIFE — MacBook Air delivers incredible battery life with amazing performance, so you can power through a full day of classes without worrying about plugging in.
- A BRILLIANT 13.6-INCH DISPLAY* — The gorgeous Liquid Retina display on MacBook Air supports 1 billion colors, making photos and videos pop with rich contrast and sharp detail, and text appears supercrisp. So everything — from class presentations to movies to games — looks truly stunning.
Remove and add the host again
In System Settings > Privacy & Security > Screen & System Audio Recording, turn the host entry off, quit the host, then add or re-enable it and relaunch. This refreshes the per-application approval without changing your script.
Check the test window
Bring Finder or another normal window to the front and repeat the minimal command. A result that shows Finder but not a particular browser, video player, remote-desktop session, or security-sensitive window is consistent with that application’s own capture policy.
Separate authorization from installation
PyAutoGUI requires Pillow for screenshots. Missing imports, an incompatible environment, or a broken Pillow install produces Python errors rather than a valid wallpaper-only image. Reinstall or repair packages only after authorization is confirmed; package work cannot grant a TCC privacy permission.
Use a diagnostic script before restoring automation
Save this script as screen_test.py and run it in the approved host:
Rank #3
- AN AMAZING MAC AT A SURPRISING PRICE — With an incredibly portable and durable aluminum design, up to 16 hours of battery life,* and the A18 Pro chip, MacBook Neo is ready to go wherever school takes you.
- FOUR STUNNING COLORS. ONE DURABLE DESIGN — Choose from four beautiful colors — Silver, Blush, Citrus, or Indigo — each with a color-coordinated keyboard. And MacBook Neo is made with a durable recycled aluminum enclosure that helps it reach 60 percent recycled content by weight — the most ever in any Apple product.*
- FLY THROUGH EVERYDAY ASSIGNMENTS — Whether you’re cramming for finals, using Apple Intelligence* to summarize class notes, creating presentations, or even playing the latest Apple Arcade game,* MacBook Neo delivers the performance and AI capabilities you need to get things done.
- UP TO 16 HOURS OF BATTERY LIFE — MacBook Neo delivers all day battery life, so you can power through from early morning classes to late night study sessions without worrying about plugging in.
- A VIBRANT 13-INCH DISPLAY* — The gorgeous Liquid Retina display on MacBook Neo supports 1 billion colors, so photos and videos pop and text is crisp for easy reading.
import pyautogui
image = pyautogui.screenshot()
print("size:", image.size)
image.save("pyautogui-screen.png")Open pyautogui-screen.png. Once it contains application windows, test your original region, delay, and image-matching logic one change at a time. Keeping the diagnostic script separate prevents a selector miss or an early click from being mistaken for a capture-permission failure.
Common symptoms and the right response
| Symptom | Likely cause | Action |
|---|---|---|
| Wallpaper and menu bar only | The calling host is not approved for Screen Recording, or the old process is still running. | Enable the actual host, quit it completely, relaunch, and run the full-screen test. |
| The permission toggle is on, but nothing changes | A different process owns the capture call. | Run the test from the enabled host; authorize the IDE, notebook, helper, or packaged app that actually executes Python. |
| macOS never displayed a prompt | The first-failure dialog is not guaranteed. | Open the Privacy & Security panel manually and add or re-enable the host. |
| Only one application is blank | That application may protect its own pixels. | Test Finder or another ordinary window before changing PyAutoGUI. |
| Clicks or typing fail after screenshots work | Accessibility or Input Monitoring is a separate permission. | Grant the relevant category to the same host if the automation action requires it. |
| Import or dependency traceback | PyAutoGUI/Pillow environment problem, not a privacy-filtered image. | Repair the Python environment after confirming the host authorization. |
| A small region is blank while full screen works | Incorrect coordinates, scaling, or a protected window under that rectangle. | Capture full screen, verify coordinates and display scaling, then retry the region. |
Make captures reliable in scripts
Keep the first test deterministic
Use a fixed output path and print the returned image size. Avoid image matching, window movement, and clicks until the pixels are present. This separates authorization failures from timing and coordinate bugs.
Account for display layout
After permission works, a region is expressed in screen coordinates. On multi-display setups, the origin can be outside the primary display and Retina scaling can make logical coordinates differ from saved-pixel dimensions. Print image.size, capture the whole desktop once, and derive the region from that verified coordinate system.
Do not confuse a stale process with a stale file
Opening an old PNG can make a successful run look unchanged. Write to a new filename or remove the previous file before each test, and verify its modification time while the host is freshly launched.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsRank #4
- AN AMAZING MAC AT A SURPRISING PRICE — With an incredibly portable and durable aluminum design, up to 16 hours of battery life,* and the A18 Pro chip, MacBook Neo is ready to go wherever school takes you.
- FOUR STUNNING COLORS. ONE DURABLE DESIGN — Choose from four beautiful colors — Silver, Blush, Citrus, or Indigo — each with a color-coordinated keyboard. And MacBook Neo is made with a durable recycled aluminum enclosure that helps it reach 60 percent recycled content by weight — the most ever in any Apple product.*
- FLY THROUGH EVERYDAY ASSIGNMENTS — Whether you’re cramming for finals, using Apple Intelligence* to summarize class notes, creating presentations, or even playing the latest Apple Arcade game,* MacBook Neo delivers the performance and AI capabilities you need to get things done.
- UP TO 16 HOURS OF BATTERY LIFE — MacBook Neo delivers all day battery life, so you can power through from early morning classes to late night study sessions without worrying about plugging in.
- A VIBRANT 13-INCH DISPLAY* — The gorgeous Liquid Retina display on MacBook Neo supports 1 billion colors, so photos and videos pop and text is crisp for easy reading.
Or skip the browser setup
If your goal is a clean website image rather than interactive desktop automation, ScreenshotNeo captures a URL server-side with one request. It removes cookie and consent banners, newsletter popups, and chat widgets before the capture; bot checks, blank pages, failed loads, timeouts, and cache hits are not billed. Every response identifies the outcome with X-Page-Verdict and X-Billed headers. An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.
Use the ScreenshotNeo documentation for authentication and the full option list. The same endpoint supports PNG, JPEG, WebP, or PDF output; full-page capture with lazy images loaded; CSS-selector element capture; dark mode; 12 device presets or any viewport; Retina scale; PDF paper size, margins, landscape and page ranges; custom CSS and JavaScript; pre-capture clicks; hidden selectors; waits for a selector, delay, or network idle; request, ad, tracker, and resource-type blocking; custom headers, cookies, user agents and Authorization; timezone and geolocation; transparent backgrounds; image resizing; selectable cache TTL; signed links; asynchronous jobs with signed webhooks; bulk capture of up to 100 URLs per call; a usage API; and an OpenAPI specification. Common parameter names used by other screenshot APIs also work, which reduces migration changes.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport 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)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);The free plan includes 1,000 shots per month with no card. Paid plans are Starter $5 for 3,000 shots, Growth $15 for 15,000, Pro $39 for 60,000, Scale $99 for 250,000, and Business $249 for 1,000,000; yearly billing provides two months free, and every feature is included on every plan. Create an account at ScreenshotNeo’s free sign-up page.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.FAQ
Will granting Screen Recording let PyAutoGUI capture every window?
No. It authorizes the host to read protected screen content, but an individual application can still restrict its own pixels. Validate with Finder or another ordinary window.
Should I authorize Terminal if I normally run the script in an IDE?
Authorize the application that launches the capture call. A successful Terminal test does not automatically authorize an IDE, notebook kernel, helper, or packaged app.
Best Value
- SUPERCHARGED BY M5 — The 14-inch MacBook Pro with M5 brings next-generation speed and powerful on-device AI to personal, professional, and creative tasks. Featuring all-day battery life and a breathtaking Liquid Retina XDR display with up to 1600 nits peak brightness, it’s pro in every way.*
- HAPPILY EVER FASTER — Along with its faster CPU and unified memory, M5 features a more powerful GPU with a Neural Accelerator built into each core, delivering faster AI performance. So you can blaze through demanding workloads at mind-bending speeds.
- BUILT FOR APPLE INTELLIGENCE — Apple Intelligence is the personal intelligence system that helps you write, express yourself, and get things done effortlessly. With groundbreaking privacy protections, it gives you peace of mind that no one else can access your data — not even Apple.*
- ALL-DAY BATTERY LIFE — MacBook Pro delivers the same exceptional performance whether it’s running on battery or plugged in.
- APPS FLY WITH APPLE SILICON — All your favorites, including Microsoft 365 and Adobe Creative Cloud, run lightning fast in macOS.*
Can reinstalling PyAutoGUI repair a wallpaper-only screenshot?
Not when the file is a valid image containing the wallpaper and menu bar. That symptom is produced by macOS privacy filtering; reinstall only for actual import or dependency errors.
Frequently Asked Questions
Will granting Screen Recording let PyAutoGUI capture every window?
No. It authorizes the host to read protected screen content, but an individual application can still restrict its own pixels. Validate with Finder or another ordinary window.
Should I authorize Terminal if I normally run the script in an IDE?
Authorize the application that launches the capture call. A successful Terminal test does not automatically authorize an IDE, notebook kernel, helper, or packaged app.
Recommended Free Tools
Can reinstalling PyAutoGUI repair a wallpaper-only screenshot?
Not when the file is a valid image containing the wallpaper and menu bar. That symptom is produced by macOS privacy filtering; reinstall only for actual import or dependency errors.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
