{"id":9235,"library":"pyscreenshot","title":"Pyscreenshot","description":"Pyscreenshot is a Python library (version 3.1) designed for taking screenshots across various operating systems. It acts as a pure Python wrapper around existing backend tools. While often considered 'obsolete' in favor of Pillow's native ImageGrab on Linux/macOS, it remains useful for its flexible backend support, Wayland compatibility, and optional subprocess handling. The library's release cadence is irregular, with the latest major update in March 2023.","status":"active","version":"3.1","language":"en","source_language":"en","source_url":"https://github.com/ponty/pyscreenshot","tags":["screenshot","image-processing","cross-platform","wrapper","gui-automation"],"install":[{"cmd":"pip install pyscreenshot Pillow","lang":"bash","label":"Install Pyscreenshot and Pillow"}],"dependencies":[{"reason":"Required for handling the captured image in memory (e.g., saving to file, displaying).","package":"Pillow","optional":false},{"reason":"Used internally by pyscreenshot for calling external programs.","package":"EasyProcess","optional":true},{"reason":"Used internally for generating command-line interfaces.","package":"entrypoint2","optional":true},{"reason":"A fast, pure Python, multiplatform backend.","package":"MSS","optional":true},{"reason":"Used for D-Bus calls, relevant for some Wayland backends.","package":"jeepney","optional":true}],"imports":[{"symbol":"ImageGrab","correct":"import pyscreenshot as ImageGrab"}],"quickstart":{"code":"import pyscreenshot as ImageGrab\nimport os\n\n# Grab the entire screen\nim = ImageGrab.grab()\n\n# Save image to a file\nfile_path = \"screenshot.png\"\nim.save(file_path)\nprint(f\"Screenshot saved to {file_path}\")\n\n# Optionally grab a specific region (bbox = (left, top, right, bottom))\n# im_region = ImageGrab.grab(bbox=(10, 10, 510, 510))\n# im_region.save(\"screenshot_region.png\")\n# print(\"Region screenshot saved to screenshot_region.png\")\n\n# To display the image (requires an image viewer configured for .show())\n# im.show()","lang":"python","description":"Captures the entire screen and saves it as a PNG file. You can also specify a bounding box for partial screen captures. Ensure Pillow is installed to save and display images."},"warnings":[{"fix":"Consider using `from PIL import ImageGrab` directly if Pillow meets your needs.","message":"Pyscreenshot is often considered obsolete as Pillow's native ImageGrab module now supports Linux and macOS. Use Pillow directly unless you need pyscreenshot's specific backend flexibility or Wayland support.","severity":"deprecated","affected_versions":"All versions"},{"fix":"Experiment with different backends (e.g., `ImageGrab.grab(backend='grim')` on Sway) or be aware of desktop environment behaviors. Check `xdg-desktop-portal` settings for confirmation dialogs.","message":"On Wayland, certain desktop environments (KDE, GNOME) might display on-screen notifications or flash effects during a screenshot, or `xdg-desktop-portal` might trigger a confirmation dialog. Not all Wayland compositors are equally supported by all backends.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Adjust OS display scaling to 100% if encountering this issue, or explore alternative screenshot tools if this is a persistent problem in your environment.","message":"If the operating system's display zoom factor is applied, `ImageGrab.grab()` may not capture the full screen correctly, resulting in black borders or incomplete images.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Run your Python script from a command-line terminal instead of IDLE. If hanging persists, try `im = ImageGrab.grab(childprocess=False)` to disable subprocess isolation for the backend.","message":"Running `pyscreenshot` commands directly in IDEs like IDLE can cause the application to hang or freeze.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Use `ImageGrab.grab()` to get an `Image` object and then `im.save()` for more reliable control over saving, format, and region.","message":"The `grab_to_file` function (if used) might ignore the `bbox` parameter, always capturing the entire screen, and may struggle with image formats other than PNG.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install one or more suitable backend tools for your operating system (e.g., `sudo apt-get install scrot` on Ubuntu/Debian, `pip install Pillow mss`). Check `pyscreenshot`'s GitHub for backend compatibility lists. For Wayland, `grim` works well on Sway, but other backends might have issues on GNOME/KDE.","cause":"Often due to missing system-level backend dependencies or Wayland-specific issues. Pyscreenshot relies on external tools (e.g., `scrot`, `gnome-screenshot`, `grim`, `maim`, `ImageMagick`, `xdg-desktop-portal`, `Pillow`, `MSS`, `PyQt5`, `PySide2`, `wxPython`) that need to be installed on your system.","error":"pyscreenshot black screenshots (or) pyscreenshot doesn't work on Linux"},{"fix":"Run your script from a command-line terminal. If the problem persists, try disabling child processes: `im = ImageGrab.grab(childprocess=False)`.","cause":"This can occur when running from certain IDEs like IDLE or due to issues with backend subprocesses.","error":"Python script hangs/freezes when taking a screenshot with pyscreenshot"},{"fix":"Set your operating system's display scaling to 100% if possible. If this is not an option, you might need to try different backends or consider other screenshot libraries that handle scaling better.","cause":"Operating system display scaling (zoom factor) can interfere with how `pyscreenshot` or its underlying backends calculate screen dimensions, leading to incomplete captures.","error":"ImageGrab.grab() captures only a portion of the screen or has black areas when OS zoom is enabled."}]}