PyScreeze

What it is and what it does

PyScreeze is a cross-platform screenshot and image-location library for Python. It captures the screen as an Image object (via Pillow) and can save screenshots to disk. More importantly, it finds where a given image appears on screen by comparing pixel data, returning coordinates that can be used to automate clicks or other interactions—useful for GUI testing, automation scripts, and visual verification tasks.

The library provides locate functions that search for template images on screen or within other images, returning bounding-box tuples (left, top, width, height) or center coordinates. It also supports pixel-level operations: reading RGB values at specific coordinates and checking whether a pixel matches an expected color within a tolerance. On a typical 1920×1080 screen, screenshot capture takes roughly 100 milliseconds and locate operations take 1–2 seconds; optional OpenCV integration can reduce locate time to under 1 millisecond.

Use it for:

• Automate GUI testing by locating UI elements (buttons, fields) on screen and verifying their presence
• Build screen-monitoring scripts that detect when specific images or conditions appear on display
• Create robot process automation (RPA) workflows that click or interact with application windows by visual coordinates
• Verify pixel colors at known screen positions to detect state changes or alerts in applications
• Capture and archive screenshots programmatically for logging, debugging, or compliance documentation

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

PyScreeze captures screenshots and locates images within them, returning pixel coordinates or Image objects for programmatic screen automation and visual testing.

Yes, if you need cross-platform screenshot capture and image-location for automation or testing. Install friction is moderate (platform-specific setup on Linux) and maintenance is dormant but not abandoned. No known vulnerabilities. Be aware that Pillow's security requirements mean Python 3.5 users face outdated dependencies; modern Python versions are safer. Suitable for automation scripts, GUI testing, and visual verification workflows.

Install

pyscreeze on PyPI

pip install pyscreeze

uv add pyscreeze

poetry add pyscreeze

Installing PyScreeze

Before you install

High install friction due to platform-specific fallback dependencies. On Ubuntu with X11, requires manual `sudo apt install python3-xlib`. Dormant maintenance (last release 724 days ago), though repository is not archived and has recent commits.

License in practice

MIT license is permissive; you may use, modify, and distribute PyScreeze freely in commercial and open-source projects with minimal restrictions.

Quickstart

pip install pyscreeze
import pyscreeze
im = pyscreeze.screenshot()
pos = pyscreeze.locateCenterOnScreen('button.png')

On Ubuntu with X11, manually run `sudo apt install python3-xlib` before use. Pillow 8.3.2+ required for security; older versions have known vulnerabilities.

Verify before relying

• Whether the package works reliably with modern Python 3.10+ given dormant maintenance status
• Current state of fallback screenshot methods (screencapture, gnome-screenshot) on recent OS versions
• Performance characteristics of image location on high-DPI or multi-monitor setups

Package facts

Evidence: pyscreeze-1.0.1.tar.gz

Keywords: screenshot, screen, screencap, capture, scrot, screencapture, image

Tags

More Utilities packages