If Pillow’s ImageGrab or a Windows BitBlt capture shows the desktop background but not the application you expected, first identify what you are trying to capture: the composed screen, a rectangle on it, or one specific window. Then test the capture option that matches that target. For a layered window, try Pillow’s Windows-only include_layered_windows=True; for an individual window, use its HWND with Pillow 11.2.1 or later. If neither fits, check whether the target window excludes itself from capture. A background-only image does not, by itself, prove a single cause or guarantee that one flag will fix every application.
First identify the capture target
These capture goals use different paths, so distinguish them before changing flags:
- Composed desktop: Capture what is displayed across the screen or screens.
- Screen rectangle: Capture pixels in a specified region, typically with Pillow’s
bboxargument. - One window: Capture a particular window identified by its Windows handle (HWND), rather than a rectangle of visible desktop pixels.
In Pillow, ImageGrab.grab() without a bounding box captures the full screen. A bbox selects a region. On Windows, all_screens=True includes all monitors; when that option is used, the top-left coordinate can be negative. Confirm that the coordinates and capture mode actually cover the target. Pillow’s current ImageGrab documentation describes these parameters and their platform support.
If your goal is one window, a screen rectangle may not be the right test: it captures screen pixels in an area, not an abstract window target. Recent Pillow versions also support Windows window capture by HWND. If you are using direct Win32 BitBlt, record the exact source handle, destination, rectangle, raster-operation code, and flags; those details are needed to distinguish a call mismatch from behavior specific to the target window.
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 errorsTry layered-window capture when that matches the missing content
A window can be layered above another window or the desktop. Pillow’s include_layered_windows option is Windows-only, defaults to False, and was added in Pillow 6.1.0. If the omitted content is a layered window, test with it enabled:
from PIL import ImageGrab
image = ImageGrab.grab(include_layered_windows=True)
image.save("capture.png")For direct Windows capture, Microsoft documents the CAPTUREBLT raster-operation flag for BitBlt. It says that the flag “Includes any windows that are layered on top of your window in the resulting image.” See the Microsoft BitBlt function documentation for the API and flag details.
These are targeted tests for layered-window behavior, not universal fixes. In particular, enabling layered-window capture does not establish why a fullscreen application is missing, nor does the documentation promise it will capture every rendering path. Avoid changing unrelated parameters until you have verified the capture target and whether layering is relevant.
For a single window, use the HWND option supported by your Pillow version
Pillow supports passing a Windows HWND to ImageGrab.grab(window=...) to capture a particular window. Windows support for this argument was added in Pillow 11.2.1. Check the installed version and ensure the handle belongs to the intended window before trying it:
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →from PIL import ImageGrab
hwnd = 123456 # Replace with the HWND of the intended window.
image = ImageGrab.grab(window=hwnd)
image.save("window.png")The example is runnable once hwnd is replaced with a valid handle obtained by your application. The documentation does not promise that every application or content type will be captured. If you pass an invalid or unrelated handle, the test does not tell you whether the intended window is capturable.
If the call raises an argument or compatibility error, verify the Pillow version before changing the code: a release earlier than 11.2.1 does not have the documented Windows support for the window argument. For a desktop or region capture instead, use the appropriate full-screen or bbox form rather than substituting a window handle.
Rank #3
Check whether the target window is excluded from capture
Windows provides SetWindowDisplayAffinity for an application to specify where its top-level window content may be displayed. A window using WDA_EXCLUDEFROMCAPTURE is omitted from capture. Microsoft says this value is supported starting with Windows 10 version 2004; on earlier Windows versions it behaves as if WDA_MONITOR were applied. The API only works when Desktop Window Manager (DWM) is composing the desktop.
This is a diagnostic possibility, not a setting you can necessarily change for a third-party application. The API is designed for an application to protect its own window content. Microsoft also cautions that “there is no guarantee that using SetWindowDisplayAffinity and GetWindowDisplayAffinity … will strictly protect windowed content.” Read the SetWindowDisplayAffinity function documentation for the platform caveats.
If capture exclusion seems plausible, record the target application and Windows version and check whether the application is known to protect its content. Do not assume that the display-affinity API offers a legitimate or available way to override another program’s choice.
Use this diagnostic sequence
- Write down the intended target. Is it the full composed desktop, a rectangle, or one window? Note the monitor arrangement and whether the target is fullscreen, minimized, occluded, or layered.
- Verify the call matches the target. For Pillow, check whether you supplied a
bbox, usedall_screens, or passed a window handle. For Win32, record the actualBitBltarguments and flags. - Test layered content only if applicable. For Pillow, try
ImageGrab.grab(include_layered_windows=True). For directBitBlt, check whether the documentedCAPTUREBLTflag is appropriate. - For one-window capture, check Pillow compatibility. Use
window=hwndonly with Windows support in Pillow 11.2.1 or newer, and verify the HWND identifies the intended window. - Investigate capture exclusion if the earlier tests do not explain it. A target application may use display affinity or another app-specific capture behavior. The cited documentation does not establish one universal explanation.
- Collect the details needed to reproduce the symptom. Record Windows version and build, Pillow version, exact code and flags, capture goal, bounding box, monitor layout and scaling, target application, and whether it is fullscreen, layered, minimized, occluded, or known to use capture protection.
Common symptoms, causes to check, and next steps
| Symptom | What to check | Next step |
|---|---|---|
| The output shows the desktop but not an overlaid window. | Whether the missing window is layered and whether layered-window inclusion is disabled. | Test Pillow’s include_layered_windows=True or, for direct Win32 capture, consult the CAPTUREBLT behavior documented for BitBlt. |
| A screen grab misses the intended area or monitor. | The bbox, monitor coordinates, and use of all_screens. Multi-monitor layouts can use negative top-left coordinates. |
Confirm the rectangle is in the intended screen coordinate space and that all required monitors are included. |
| A window-specific call fails or does not target the expected window. | Whether the installed Pillow supports Windows window capture and whether the HWND is correct. |
Windows HWND support for this Pillow argument starts in version 11.2.1; verify the handle before drawing conclusions about capture behavior. |
| The target remains absent after the relevant Pillow or BitBlt option is tested. | Whether the application uses display affinity or behaves differently on its particular rendering path. | Record the application and Windows version. The cited API documents a possible exclusion mechanism, but does not establish it as the cause for every missing window. |
Or skip the browser setup:
If the job is to capture a web page rather than a Windows desktop window, ScreenshotNeo provides a one-request website screenshot API. This is a different capture target: it captures a URL in a browser, not arbitrary desktop pixels or a protected local application window. The ScreenshotNeo website describes the service; its documentation covers the API.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpReplace YOUR_API_KEY with your API key and change the URL to the page you want. The response can be a PNG, JPEG, WebP, or PDF. ScreenshotNeo accepts cookie or consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each of those steps can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers indicate the page verdict and billing status. Its MCP server offers take_screenshot, get_page_info, and capture_pdf for AI agents using Claude, Cursor, or another MCP client.
The free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots, and yearly billing gives two months free. Every feature is available on every plan. If a web-page capture fits your task, sign up for ScreenshotNeo’s free plan.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
FAQ
Does a background-only image prove Pillow has a bug?
No. The symptom alone does not distinguish a wrong capture target, layered-window behavior, display affinity, or application-specific capture behavior. A community report describes the same kind of symptom on Windows 10, but it is anecdotal rather than a general diagnosis: Stack Overflow report.
Will CAPTUREBLT make every fullscreen application capturable?
No such guarantee is established in the BitBlt documentation. It describes inclusion of layered windows above the source window, so use it to test that specific condition rather than as a general fullscreen fix.
Can I use ScreenshotNeo to capture the missing Windows application?
No. ScreenshotNeo captures websites from a URL. It does not replace Pillow or Win32 capture for local desktop pixels, nor does it override a Windows application’s capture exclusion.
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.
