pyscreenshot

By default, pyscreenshot starts backends in a subprocess for safety and isolation. For significantly better performance, you can set childprocess=False. Combining this with the mss backend often yields the best results.

import pyscreenshot as ImageGrab

# best performance
im = ImageGrab.grab(backend="mss", childprocess=False)

The library supports Wayland via:

1. xdg-desktop-portal (D-Bus: org.freedesktop.portal.Screenshot)
2. GNOME (D-Bus: org.gnome.Shell.Screenshot)
3. Grim (on Sway/compositors with wlr-screencopy-unstable-v1 support)

Decision Logic: If both Wayland and X are available, pyscreenshot prefers Wayland because Xwayland cannot be used for screenshots. It uses X only if the DISPLAY variable exists and XDG_SESSION_TYPE is not wayland.

Install pyscreenshot along with its primary dependency Pillow using pip:

python3 -m pip install Pillow pyscreenshot

You can explicitly specify which backend to use by passing the backend argument to ImageGrab.grab(). Supported backends include pil, mss, scrot, maim, imagemagick, pyqt5, pyside2, wx, gnome-screenshot, and others.

import pyscreenshot as ImageGrab

im = ImageGrab.grab(backend="scrot")

Use ImageGrab.grab() to capture the entire desktop. The returned object is a Pillow image memory object, which you can then use to save the file or perform image processing.

import pyscreenshot as ImageGrab

# grab fullscreen
im = ImageGrab.grab()

# save image file
im.save("fullscreen.png")

Use the bbox parameter in ImageGrab.grab() to capture a specific rectangular region. The bbox argument expects a tuple in the format (X1, Y1, X2, Y2).

import pyscreenshot as ImageGrab

# part of the screen
im = ImageGrab.grab(bbox=(10, 10, 510, 510))  # X1,Y1,X2,Y2

# save image file
im.save("box.png")

To see which backends are installed and available on your system, run the following command in your terminal:

python3 -m pyscreenshot.check.versions

You can benchmark the speed of different backends using the pyscreenshot.check.speedtest module. To test the fastest possible configuration (without subprocesses), use the --childprocess 0 flag.

# Default settings (safest)
python3 -m pyscreenshot.check.speedtest

# Without subprocess (fastest)
python3 -m pyscreenshot.check.speedtest --childprocess 0

Use the print_backend_version command to retrieve the version string of a specific screenshot backend (e.g., scrot, wx). If no backend is specified, it attempts to print the version of the currently active backend. If the backend is invalid or an error occurs, a warning is logged and an empty string is printed.

python -m pyscreenshot.cli.print_backend_version <backend>
# Example:
python -m pyscreenshot.cli.print_backend_version scrot

The pyscreenshot CLI allows you to capture the screen or specific regions and save them to a file or display them immediately.

Arguments:

• filename: The output file path where the screenshot will be saved.
• bbox: Bounding box coordinates in the format x1:y1:x2:y2 (e.g., 0:0:800:600) to capture a specific part of the screen.
• backend: Force a specific backend (e.g., scrot, wx) if the automatic selection fails or you have a preference.
• show: A flag to display the captured image immediately after capture.

# Example: Capture a specific region and save to a file
pyscreenshot 10:10:500:500:output.png

# Example: Capture the whole screen and show it
pyscreenshot --show

# Example: Force a specific backend
pyscreenshot --backend scrot:image.png