10.2.0

❤️ Big shout out to @jholveck and @halldorfannar for this huge release. It will pave a brighter future for the project. Warm thank you to both of you.

---

Python-MSS 10.2.0

This is version 10.2.0 of Python-MSS, the ultra-fast cross-platform multiple screenshots module.

Release date: 2026-04-23

This release lays the groundwork for upcoming improvements planned for MSS 11.0, while remaining fully backward-compatible. It also improves performance, reliability, and multithreaded behavior, and introduces several new features for working with multi-monitor systems.

If your code works with previous versions of MSS, it should continue to work unchanged in 10.2.0.

---

Highlights

New API

In 10.2, MSS introduces a new API. The new design lets the MSS project introduce more significant internal changes, without introducing compatibility problems.

Programs using the old API will continue to work in 10.2.0, and most of them will continue to work with 11.0 and beyond.

Previously, MSS would provide the user with an OS-specific MSS class. In the new API, the user always sees a single class: mss.MSS.

The existing mss.mss factory function will continue to work in 11.0, and will continue to work for as long as is reasonable. However, the mss.MSS constructor is preferred for new code.

The existing mss.{platform}.MSS types are deprecated in 10.2.0. (This means the mss.darwin.MSS, mss.linux.MSS, and mss.windows.MSS classes.) They will continue to work. In 11.0, MSS will remove these classes, but to help with backwards compatibility, they will become deprecated factory functions, returning an instance of mss.MSS. Users who use mss.{platform}.MSS as functions can continue to do so. Users who use these as type declarations may update their code to use mss.MSS in 10.2, and may be required to do so in 11.0.

Speaking of types, the MSSBase class is deprecated in 10.2.0. Most users won’t care about that, some type declarations may need to change to mss.MSS.

Where possible, deprecated functionality emits a DeprecationWarning. However, note that these are ignored by default, unless triggered by code in __main__. If you want to see these DeprecationWarning messages, you may run your program under python -Wd, or with the environment variable PYTHONWARNINGS=default (or error). See the Python documentation chapter “Warning Control” for more details.

Many of the API docs are removed, since this change removes much of the API surface. However, they are still in available for backwards-compatibility.

Again, existing working code will continue to work in 10.2 unchanged. However, we recommend that users change the code and type declarations to use mss.MSS.

Summary of deprecations:

• mss.mss: Change to mss.MSS. Will continue to work in 11.0.
• mss.{platform}.MSS: Change to mss.MSS. Code will continue to work in 11.0. Types will need to be changed by 11.0.
• mss.base.MSSBase: (Only valid as a type) Change to mss.MSS by 11.0.

With this change, we are also documenting the MSS versioning policy. MSS has always used Semantic Versioning, but the new policy clearly spells out the details.

Demo Applications

The repository now includes several full demo programs under demos/ showing common screenshot-processing workflows built on MSS.

These examples are intended as learning resources and reference implementations. The demos include extensive comments explaining the pipeline architecture and performance considerations involved in real-world screenshot processing, as well as how to use MSS with several popular libraries.

Included demos:

Video Recorder

Records the screen to a video file using MSS frames.

TinyTV Streamer

Streams the screen as MJPEG to a TinyTV device.

Cat Detector

Demonstrates real-time computer vision by detecting cats appearing on the screen.

While playful, these examples illustrate techniques for:

• video capture
• streaming
• real-time analysis of screenshots
• multithreaded pipelining
• integration with PyAV, Pillow, and PyTorch

Richer Monitor Metadata

If you currently use sct.monitors[1] to select the primary display, you may prefer the new sct.primary_monitor property.

Monitor dictionaries now include additional metadata to help applications identify displays reliably:

• is_primary — whether this monitor is the primary display
• name — human-readable device name
• unique_id — stable identifier for the display

These values make it easier to:

• detect the primary monitor
• select a specific display across runs
• handle dynamic multi-monitor configurations

These new values are only present if they can be detected. In some cases (such as with a very old monitor), they may not be available.

A new convenience property has also been added:

sct.primary_monitor

This returns the monitor dictionary corresponding to the system’s primary display.

Currently available on:

• Windows
• Linux

Support for macOS will be added in the future.

Multithreading Improvements

Multithreaded usage of MSS has been improved and clarified.

In 10.2.0:

• An MSS instance can safely be passed between threads
• Calls to grab() on the same MSS instance remain serialized, but are now guaranteed to be safe
• Multiple MSS instances can capture concurrently, allowing parallel capture across threads

Previously, some internal locking effectively serialized capture across all MSS usage. In 10.2.0, locking is now per instance, allowing independent MSS objects to perform captures simultaneously.

The documentation has also been expanded to describe MSS’s supported multithreading guarantees.

On Linux, the new XCB-based backend further improves the reliability of multithreaded usage compared to the previous Xlib-based implementation.

---

Improved Linux Capture Backend

The Linux capture implementation has been significantly modernized to reduce capture overhead and improve multithreaded reliability.

New XCB Backend

MSS now includes an XCB-based backend stack, replacing the previous Xlib-based implementation. XCB provides more predictable thread-safety and improves the reliability of multithreaded capture.

The previous Xlib implementation remains available as a fallback for systems where the XCB backend cannot be used. See the GNU/Linux usage documentation for configuration details.

Shared-Memory Capture (XShm)

Linux now uses XShmGetImage by default, allowing MSS to capture screenshots using the X11 shared-memory extension when it is available.

With this method, the X server writes pixel data directly into a shared memory buffer provided by the client, avoiding the extra copy required by the traditional XGetImage path. This reduces overhead during capture and dramatically improves performance for applications that take screenshots frequently.

If shared memory is not available, MSS automatically falls back to XGetImage.

Capture Performance

The new Linux backend can significantly reduce screenshot capture overhead.

In local testing (local desktop system, Debian testing, X11, 4K display), a tight loop capturing the full screen (1000 iterations, best of three runs) improved from:

10.1.0: 46.2 ms per screenshot
10.2.0:  9.48 ms per screenshot

This represents roughly a 5× reduction in capture time in that environment.

The improvement comes primarily from the new backend architecture and the use of the X11 shared-memory extension (XShmGetImage), which avoids an additional memory copy when transferring pixel data from the X server.

Actual performance improvements will vary depending on factors such as:

• display resolution
• X server configuration
• hardware
• whether the shared-memory capture path is available

Windows Improvements

Windows has received capture-reliability improvements and we have named the backend, for operational consistency with Linux.

Capture with CreateDIBSection

The Windows screenshot implementation now uses CreateDIBSection instead of GetDIBits.

This reduces memory overhead and improves reliability during long capture sessions.

Additional improvements include:

• improved Win32 error handling and diagnostics
• fixes for capture failures during extended recordings

Restructure

The existing GDI implementation has been converted to a named backend, "gdi".
It is currently the only backend for Windows and therefore the default. We plan
to add a DXGI backend in the near future.

These changes were made while keeping backwards compatibility with the existing API.

macOS Stability Fix

A memory leak in the macOS backend has been fixed.

---

Deprecations and Upcoming Changes (Planned for 11.0)

This release introduces deprecations that will take effect in MSS 11.0.

These changes are intended to improve:

• API clarity
• type safety
• future GPU capture support
• internal performance

Most users will not need to change anything immediately.

If you are unsure whether you are affected, search your codebase for the names mentioned below.

Python 3.9 EOL

Python 3.9 reached end-of-life on October 31, 2025. It is no longer receiving any updates, even security updates.

The MSS project has chosen to end support for Pyth...

10.1.0

❤️ contributors: @brycedrennan

• 🚀 Mac: up to 60% performances improvement by taking screenshots at nominal resolution (e.g. scaling is off by default). To enable back scaling, set mss.darwin.IMAGE_OPTIONS = 0. (#257)
• 📜 docs: use the shibuya theme

v10.0.0

❤️ contributors: @kianmeng, @shravanasati, @mgorny

• ⚠️ removed support for Python 3.8
• 🐍 added support for Python 3.14 (#300)
• 🐛 Linux: fixed a threadding issue in .close() when calling XCloseDisplay() (#251)
• ⚙️ Linux: minor optimization when checking for a X extension status (#251)
• 🧙 tweaked ruff rules (#306)
• 📜 improved the documentation (#284, #295)

v9.0.2

❤️ contributors: @Andon-Li

• 🐍 added support for Python 3.13
• 🚀 leveled up the packaging using hatchling
• 🧙 used ruff to lint the code base (#275)
• 🐛 MSS: fixed Pixel model type (#274)
• ⚙️ MSS: minor optimization when using an output file format without date (#275)
• CI: automated release publishing on tag creation

9.0.1

• 🐛 CLI: fixed entry point not taking into account arguments (#255)

9.0.0

❤️ contributors: @mgorny, @CTPaHHuK-HEbA

• 🐞 Linux: add failure handling to XOpenDisplay() call (fixes #246)
• 🚀 Mac: tiny improvement in monitors finding
• 🐛 Windows: refactored how internal handles are stored (fixes #198)
• 🐛 Windows: removed side effects when leaving the context manager, resources are all freed (fixes #209)
• CI: run tests via xvfb-run on GitHub Actions (#248)
• tests: enhance test_get_pixels.py, and try to fix a random failure at the same time (related to #251)
• tests: use PyVirtualDisplay instead of xvfbwrapper (#249)
• tests: automatic rerun in case of failure (related to #251)

8.0.3

❤️ contributors: @mgorny, @relent95

• 🐍 added support for Python 3.12
• 💯 MSS: added PEP 561 compatibility
• 🐛 MSS: include more files in the sdist package (#240)
• 🐞 Linux: restore the original X error handler in .close() (#241)
• 🐛 Linux: fixed XRRCrtcInfo.width, and XRRCrtcInfo.height, C types
• doc: use markdown for the README, and changelogs
• ⚠️ dev: renamed the master branch to main
• 🐛 dev: review the structure of the repository to fix/improve packaging issues (#243)

8.0.2

• 🐞 fixed SetuptoolsDeprecationWarning: Installing 'XXX' as data is deprecated, please list it in packages
• 🐛 CLI: fixed arguments handling

8.0.1

• 🐞 MSS: ensure --with-cursor, and with_cursor argument & attribute, are simple NOOP on platforms not supporting the feature
• 🐞 CLI: do not raise a ScreenShotError when -q, or --quiet, is used but return 1
• 🐛 tests: fix test_entry_point() with multiple monitors having the same resolution

8.0.0

• ⚠️ removed support for Python 3.6
• ⚠️ removed support for Python 3.7
• 🐛 MSS: fixed PEP 484 prohibits implicit Optional
• 💯 MSS: the whole source code was migrated to PEP 570 (Python positional-only parameters)
• 🆕 Linux: added mouse support (related to #55)
• 🐛 Linux: reset the X server error handler on exit to prevent issues with Tk/Tkinter (fixes #220)
• 🐛 Linux: refactored how internal handles are stored to fix issues with multiple X servers (fixes #210)
• 🐛 Linux: removed side effects when leaving the context manager, resources are all freed (fixes #210)
• 🆕 CLI: added --with-cursor argument
• tests: added PyPy 3.9, removed tox, and improved GNU/Linux coverage