How to Fix PIL ImportError: No Module Named _grabscreen
Fix the legacy _grabscreen import error by using current Pillow, the correct Python environment, and the right display prerequisites.

Direct answer: ImportError: No module named _grabscreen usually comes from an old PIL or Pillow ImageGrab implementation. Install or upgrade Pillow in the exact Python environment that runs your script, import ImageGrab from PIL, and then check the operating system’s display and capture prerequisites. Current Pillow documents ImageGrab.grab() on Windows, macOS, and Linux. Linux support was added in Pillow 7.1.0, while macOS support dates to Pillow 3.0.0. These are historical feature milestones, not recommended versions to install.
The traceback does not identify the active Pillow version by itself. A different interpreter, virtual environment, IDE, notebook kernel, or system Python may still be loading an older copy.
1. Confirm the interpreter and the imported package
Run these commands with the same interpreter that runs your application. Using python -m pip ties pip to that interpreter.

python --version
python -c "import sys; print(sys.executable)"
python -m pip show Pillow
python -c "import PIL, sys; print('Pillow:', getattr(PIL, '__version__', 'unknown')); print('PIL path:', PIL.__file__); print('Python:', sys.executable)"
If your system uses python3, replace python consistently. In a virtual environment, activate it first. In a notebook, inspect sys.executable from a cell; installing Pillow into a shell environment does not change the notebook kernel automatically.
2. Install or update Pillow in that environment
python -m pip install --upgrade Pillow
If the project has a dependency file, record the chosen version after confirming compatibility:
python -m pip freeze | python -c "import sys; print(''.join(line for line in sys.stdin if line.lower().startswith('pillow==')))"
Do not install a package named _grabscreen. It is a private implementation module used by older code paths, not the supported public API. Current code should use:
from PIL import ImageGrab
image = ImageGrab.grab()
image.save("screen.png")
Reference: Pillow ImageGrab documentation.
3. Verify a minimal capture before changing application code
Create capture_test.py:
from PIL import ImageGrab
image = ImageGrab.grab()
print(image.mode, image.size)
image.save("screen-test.png")
Run python capture_test.py. If the import succeeds but capture fails, the remaining problem is platform or display access rather than the missing private module.
Capture a region
from PIL import ImageGrab
# (left, top, right, bottom), in screen coordinates
image = ImageGrab.grab(bbox=(0, 0, 1200, 800))
image.save("region.png")
Include or exclude the pointer
from PIL import ImageGrab
image = ImageGrab.grab(include_layered_windows=True, include_cursor=False)
image.save("window.png")
Check the parameter details for your installed Pillow release in the ImageGrab reference; platform support and optional arguments vary by release.
4. Linux: check XCB and display access
Pillow uses X11 support through XCB for the normal Linux ImageGrab.grab() path. Check whether your build has that feature:

python -c "from PIL import features; print('xcb:', features.check_feature('xcb'))"
printenv DISPLAY
printenv WAYLAND_DISPLAY
Pillow documents PIL.features.check_feature("xcb") for this check. A false result means the installed build lacks XCB support; reinstall a Pillow build compatible with your system and verify its native dependencies. An empty DISPLAY in an X11 session, or an inaccessible Wayland/X11 session, can prevent capture even when the import works.
Current Pillow documentation also describes fallback utilities that may be used when available:
gnome-screenshotgrimspectacle
Install and configure the utility appropriate for your desktop distribution, then retry the minimal script. Headless CI containers generally have no accessible desktop display; a virtual display or a browser-based capture service is required for that use case.
5. Windows and macOS checks
| Platform | Checks |
|---|---|
| Windows | Confirm the script and pip use the same interpreter, then run the minimal capture. Current Pillow documents Windows support. |
| macOS | Use a current Pillow release and run the process in a logged-in graphical session with the required screen-recording permission. macOS support was added in Pillow 3.0.0. |
| Linux | Check Pillow version, XCB, display variables, session permissions, and documented fallback utilities. |
Older PIL releases may have different platform limitations. If an application cannot upgrade, evaluate a capture API compatible with its operating system and Python version instead of trying to restore the private _grabscreen import.
6. Common errors and fixes
| Error or symptom | Likely cause | Fix |
|---|---|---|
No module named _grabscreen |
Legacy PIL/Pillow ImageGrab.py is being imported. |
Upgrade Pillow with python -m pip install --upgrade Pillow in the active interpreter, then use from PIL import ImageGrab. |
No module named PIL |
Pillow is not installed in the interpreter running the script. | Run python -m pip install Pillow and verify sys.executable. |
| Upgrade appears to do nothing | IDE, notebook, service, or virtual environment uses another Python. | Compare sys.executable, PIL.__file__, and python -m pip show Pillow; restart the kernel or service. |
| Import works, capture fails on Linux | Missing XCB support, display variable, permissions, or desktop session. | Check features.check_feature('xcb'), DISPLAY/WAYLAND_DISPLAY, session access, and fallback utilities. |
| Works locally but fails in CI or Docker | No graphical display is available. | Provide an accessible display environment or use a browser/API capture workflow. |
| Blank or partial image | Window is obscured, outside the selected bounding box, or the desktop compositor/session restricts capture. | Test full-screen capture, verify coordinates and permissions, and capture from an appropriate graphical session. |
7. Reliability, performance, and cost considerations
- Reliability: Import success only proves that Python can load Pillow. Capture still depends on display-server access, permissions, native features, and session state.
- Performance: Capturing a smaller
bboxreduces the amount of screen data processed. Full-screen and high-resolution captures require more memory and disk space. - Concurrency: Desktop capture is tied to a user session. For repeatable server workloads, isolate capture workers and make display availability an explicit health check.
- Cost: Pillow itself is a local library. Infrastructure costs come from the machine, virtual display, storage, and operational maintenance needed to keep a graphical session available.
Or skip the browser setup
If your real goal is a reliable website screenshot rather than the pixels on a developer’s desktop, ScreenshotNeo provides a single HTTP request. Its capture API accepts a URL and returns PNG, JPEG, WebP, or PDF; see the API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
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)
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
Before the capture, cookie and consent banners are accepted and more than 60 known consent platforms, newsletter popups, and chat widgets are removed; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers report the page verdict and billing status. An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.
FAQ
Is _grabscreen a package I should install?
No. It is a private module name from an older implementation. Use Pillow’s public ImageGrab API.
Does upgrading Pillow guarantee that capture will work?
No. It fixes the obsolete import path, but capture still requires a supported platform, compatible build, and accessible display session.
What changed for Linux?
Current Pillow documents Linux support, added in Pillow 7.1.0, with XCB and display requirements. Older answers describing Linux as unsupported are historical.
Why does the error appear only in one application?
That application may use a different interpreter, virtual environment, notebook kernel, or vendored PIL copy. Compare the executable and PIL.__file__ from inside the failing process.


