Pyscreenshot

3.1 · active · verified Thu Apr 16

Pyscreenshot is a Python library (version 3.1) designed for taking screenshots across various operating systems. It acts as a pure Python wrapper around existing backend tools. While often considered 'obsolete' in favor of Pillow's native ImageGrab on Linux/macOS, it remains useful for its flexible backend support, Wayland compatibility, and optional subprocess handling. The library's release cadence is irregular, with the latest major update in March 2023.

Common errors

```
pyscreenshot black screenshots (or) pyscreenshot doesn't work on Linux
```
cause Often due to missing system-level backend dependencies or Wayland-specific issues. Pyscreenshot relies on external tools (e.g., `scrot`, `gnome-screenshot`, `grim`, `maim`, `ImageMagick`, `xdg-desktop-portal`, `Pillow`, `MSS`, `PyQt5`, `PySide2`, `wxPython`) that need to be installed on your system.

fix Install one or more suitable backend tools for your operating system (e.g., `sudo apt-get install scrot` on Ubuntu/Debian, `pip install Pillow mss`). Check `pyscreenshot`'s GitHub for backend compatibility lists. For Wayland, `grim` works well on Sway, but other backends might have issues on GNOME/KDE.
```
Python script hangs/freezes when taking a screenshot with pyscreenshot
```
cause This can occur when running from certain IDEs like IDLE or due to issues with backend subprocesses.

fix Run your script from a command-line terminal. If the problem persists, try disabling child processes: `im = ImageGrab.grab(childprocess=False)`.
```
ImageGrab.grab() captures only a portion of the screen or has black areas when OS zoom is enabled.
```
cause Operating system display scaling (zoom factor) can interfere with how `pyscreenshot` or its underlying backends calculate screen dimensions, leading to incomplete captures.

fix Set your operating system's display scaling to 100% if possible. If this is not an option, you might need to try different backends or consider other screenshot libraries that handle scaling better.

Warnings

deprecated Pyscreenshot is often considered obsolete as Pillow's native ImageGrab module now supports Linux and macOS. Use Pillow directly unless you need pyscreenshot's specific backend flexibility or Wayland support.
Fix: Consider using `from PIL import ImageGrab` directly if Pillow meets your needs.
gotcha On Wayland, certain desktop environments (KDE, GNOME) might display on-screen notifications or flash effects during a screenshot, or `xdg-desktop-portal` might trigger a confirmation dialog. Not all Wayland compositors are equally supported by all backends.
Fix: Experiment with different backends (e.g., `ImageGrab.grab(backend='grim')` on Sway) or be aware of desktop environment behaviors. Check `xdg-desktop-portal` settings for confirmation dialogs.
gotcha If the operating system's display zoom factor is applied, `ImageGrab.grab()` may not capture the full screen correctly, resulting in black borders or incomplete images.
Fix: Adjust OS display scaling to 100% if encountering this issue, or explore alternative screenshot tools if this is a persistent problem in your environment.
gotcha Running `pyscreenshot` commands directly in IDEs like IDLE can cause the application to hang or freeze.
Fix: Run your Python script from a command-line terminal instead of IDLE. If hanging persists, try `im = ImageGrab.grab(childprocess=False)` to disable subprocess isolation for the backend.
gotcha The `grab_to_file` function (if used) might ignore the `bbox` parameter, always capturing the entire screen, and may struggle with image formats other than PNG.
Fix: Use `ImageGrab.grab()` to get an `Image` object and then `im.save()` for more reliable control over saving, format, and region.

Install

pip install pyscreenshot Pillow Install Pyscreenshot and Pillow

Imports

ImageGrab
```
import pyscreenshot as ImageGrab
```

Quickstart

Captures the entire screen and saves it as a PNG file. You can also specify a bounding box for partial screen captures. Ensure Pillow is installed to save and display images.

import pyscreenshot as ImageGrab
import os

# Grab the entire screen
im = ImageGrab.grab()

# Save image to a file
file_path = "screenshot.png"
im.save(file_path)
print(f"Screenshot saved to {file_path}")

# Optionally grab a specific region (bbox = (left, top, right, bottom))
# im_region = ImageGrab.grab(bbox=(10, 10, 510, 510))
# im_region.save("screenshot_region.png")
# print("Region screenshot saved to screenshot_region.png")

# To display the image (requires an image viewer configured for .show())
# im.show()

view raw JSON →