{"id":2716,"library":"pyscreeze","title":"PyScreeze","description":"PyScreeze is a simple, cross-platform screenshot module for Python 3. It provides functionality to take screenshots, save them to files, and locate images within the screen. This is particularly useful for GUI automation tasks where visual elements need to be identified. The library is currently at version 1.0.1 and typically has an infrequent release cadence, with the last PyPI release in August 2024.","status":"active","version":"1.0.1","language":"en","source_language":"en","source_url":"https://github.com/asweigart/pyscreeze","tags":["screenshot","GUI automation","image recognition"],"install":[{"cmd":"pip install pyscreeze","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required 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+).","package":"Pillow","optional":false},{"reason":"Required for Linux systems (e.g., Ubuntu) using the X11 window system.","package":"python3-xlib","optional":true},{"reason":"An 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`).","package":"scrot","optional":true},{"reason":"An 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`).","package":"gnome-screenshot","optional":true},{"reason":"Optional dependency (`cv2`) that can significantly speed up image location functions if installed.","package":"opencv-python","optional":true}],"imports":[{"note":"All functions are typically accessed directly from the `pyscreeze` module, e.g., `pyscreeze.screenshot()`.","symbol":"pyscreeze","correct":"import pyscreeze"}],"quickstart":{"code":"import pyscreeze\n\n# Take a screenshot of the entire screen\nim1 = pyscreeze.screenshot()\n# Save a screenshot to a file\nim2 = pyscreeze.screenshot('my_screenshot.png')\n\n# Take a screenshot of a specific region (left, top, width, height)\n# Ensure 'image_path.png' exists for locateOnScreen to work\ntry:\n    region_screenshot = pyscreeze.screenshot(region=(0, 0, 300, 400))\n    print(f\"Screenshot of region saved as temporary file. Image object: {region_screenshot}\")\n\n    # Locate an image on the screen\n    # Replace 'path/to/your/button.png' with an actual image file on your screen\n    # Ensure an image 'button.png' is in the current directory or provide full path\n    button_location = pyscreeze.locateOnScreen('button.png', confidence=0.8)\n    if button_location:\n        print(f\"Button found at: {button_location}\")\n        center_coords = pyscreeze.center(button_location)\n        print(f\"Center of button: {center_coords}\")\n    else:\n        print(\"Button not found on screen.\")\nexcept pyscreeze.ImageNotFoundException:\n    print(\"Image not found on screen (expected for 'button.png' if not present).\")\nexcept FileNotFoundError:\n    print(\"Ensure 'button.png' exists in the current directory or provide a full path.\")\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")","lang":"python","description":"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)."},"warnings":[{"fix":"Wrap 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`.","message":"The 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`.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Ensure 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.","message":"Pillow 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.","severity":"gotcha","affected_versions":"<1.0.1"},{"fix":"Install 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.","message":"On 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.","severity":"gotcha","affected_versions":"All versions on Linux"},{"fix":"Verify 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.","message":"When 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.","severity":"gotcha","affected_versions":"All versions when used with PyAutoGUI"},{"fix":"Update calls from `pyscreeze.pixelMatchesColor((x, y), rgb_tuple)` to `pyscreeze.pixelMatchesColor(x, y, rgb_tuple)`.","message":"The `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.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Always pass a tuple of four integers, e.g., `pyscreeze.screenshot(region=(10, 20, 100, 50))`.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}