Install & Compatibility
Where this runs
tested against v1.0.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.058s · 37.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.6s · import 0.050s · 38MB
27MB installed
● package 27MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
pyscreeze
✓ import pyscreeze
✗ import pyscreeze
This quickstart demonstrates how to take full or partial screenshots and how to locate an image on the screen using `screenshot()` and `locateOnScreen()`. The `locateOnScreen()` function returns a 4-integer tuple (left, top, width, height) if found, or raises an `ImageNotFoundException` if not found (default behavior since 1.0.0).
import pyscreeze
# Take a screenshot of the entire screen
im1 = pyscreeze.screenshot()
# Save a screenshot to a file
im2 = pyscreeze.screenshot('my_screenshot.png')
# Take a screenshot of a specific region (left, top, width, height)
# Ensure 'image_path.png' exists for locateOnScreen to work
try:
region_screenshot = pyscreeze.screenshot(region=(0, 0, 300, 400))
print(f"Screenshot of region saved as temporary file. Image object: {region_screenshot}")
# Locate an image on the screen
# Replace 'path/to/your/button.png' with an actual image file on your screen
# Ensure an image 'button.png' is in the current directory or provide full path
button_location = pyscreeze.locateOnScreen('button.png', confidence=0.8)
if button_location:
print(f"Button found at: {button_location}")
center_coords = pyscreeze.center(button_location)
print(f"Center of button: {center_coords}")
else:
print("Button not found on screen.")
except pyscreeze.ImageNotFoundException:
print("Image not found on screen (expected for 'button.png' if not present).")
except FileNotFoundError:
print("Ensure 'button.png' exists in the current directory or provide a full path.")
except Exception as e:
print(f"An error occurred: {e}")
Debug
Known issues
breakingThe default behavior of `locate` functions changed in version 1.0.0. They now raise `pyscreeze.ImageNotFoundException` when an image is not found, instead of returning `None`.fixWrap calls to `locateOnScreen`, `locateCenterOnScreen`, `locateAllOnScreen`, and `locate` in a `try...except pyscreeze.ImageNotFoundException` block. Alternatively, set `pyscreeze.USE_IMAGE_NOT_FOUND_EXCEPTION = False` to revert to returning `None`.
affects: >=1.0.0
gotchaPillow version compatibility is crucial. Older versions of Pillow have known security vulnerabilities. For Python 3.6+, Pillow >= 8.3.2 is recommended. For Python 3.7+ and Wayland support on Linux, Pillow >= 9.2.0 is needed.fixEnsure you are using an up-to-date Python version (3.6+) and install or upgrade Pillow to a secure and compatible version (e.g., `pip install --upgrade Pillow`). Consult `pyscreeze/setup.py` for precise version requirements per Python version.
affects: <1.0.1
gotchaOn Linux, PyScreeze often relies on external command-line tools for screenshots (e.g., `scrot` or `gnome-screenshot`) and may require `python3-xlib` for X11 environments. These must be installed separately via the system's package manager.fixInstall necessary packages: `sudo apt install scrot` or `sudo apt install gnome-screenshot` (depending on system/preferences) and `sudo apt install python3-xlib` if using X11.
affects: All versions on Linux
gotchaWhen used with PyAutoGUI, a common issue is 'PyAutoGUI was unable to import PyScreeze' errors. This often indicates problems with PyScreeze or Pillow installations, or Python environment conflicts.fixVerify that both `pyscreeze` and `Pillow` are correctly installed and compatible with your Python version. Use virtual environments to prevent conflicts. If problems persist, try reinstalling both libraries.
affects: All versions when used with PyAutoGUI
breakingThe `pixelMatchesColor()` function in version 1.0.0 changed its argument signature. It no longer accepts a `(x, y)` tuple as the first argument; `x` and `y` must now be passed as separate arguments.fixUpdate calls from `pyscreeze.pixelMatchesColor((x, y), rgb_tuple)` to `pyscreeze.pixelMatchesColor(x, y, rgb_tuple)`.
affects: >=1.0.0
gotchaThe `region` argument for `screenshot()` must be a tuple of exactly four integers (left, top, width, height). Non-integer values or incorrect lengths will raise an error.fixAlways pass a tuple of four integers, e.g., `pyscreeze.screenshot(region=(10, 20, 100, 50))`.
affects: >=1.0.0
Upgrade
Version history
1.0.1latest on PyPI · released Aug 20, 2024
Audit
Dependencies
PillowrequiredRequired for all screenshot functionality. Specific versions are recommended/required based on Python version for security and Wayland compatibility (e.g., Pillow >= 8.3.2 for Python 3.6+, >= 9.2.0 for Python 3.7+).
python3-xliboptionalRequired for Linux systems (e.g., Ubuntu) using the X11 window system.
scrotoptionalAn external command-line tool often required for screenshot functionality on Linux/FreeBSD systems. Must be installed via system package manager (e.g., `sudo apt install scrot`).
gnome-screenshotoptionalAn external command-line tool used as a fallback or primary screenshot method on some Linux systems, especially those using Wayland with Pillow >= 9.2.0. Must be installed via system package manager (e.g., `sudo apt install gnome-screenshot`).
opencv-pythonoptionalOptional dependency (`cv2`) that can significantly speed up image location functions if installed.