---
id: pyscreeze
version: "1.0.1"
license: MIT
license_treatment: permissive
maintenance: dormant
---

# PyScreeze — A simple, cross-platform screenshot module for Python 2 and 3.

License: permissive · Maintenance: dormant · Downloads: 3.0M/mo

## 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 above — 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

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

- License: MIT (permissive)
- Python support: unspecified
- Install friction: high
- Maintenance: dormant
- Downloads: 3.0M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

screenshot capture python, image recognition on screen, locate button on screen, screen automation coordinates, visual testing automation, pixel matching detection, cross-platform screenshot, screen-automation, gui-testing, image-recognition

[View on SkillFed](https://skillfed.io/packages/pyscreeze) · [View on PyPI](https://pypi.org/project/pyscreeze/)