ScreenshotNeo

BlogHow-to

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.

By the ScreenshotNeo team30 September 20266 min read

How to Fix PIL ImportError: No Module Named _grabscreen

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.

Use the same interpreter for installation and execution so Pillow imports from the environment you repaired.
Use the same interpreter for installation and execution so Pillow imports from the environment you repaired.
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:

On Linux, module imports and display access are separate checks.
On Linux, module imports and display access are separate checks.
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-screenshot
  • grim
  • spectacle

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 bbox reduces 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.