❤️ 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 Python 3.9, in order to focus our resources on current versions of Python. Python 3.9 is still supported in the MSS 10.2 release, but MSS 11 will require Python 3.10 or later.

Deprecated Attribute

mss.ScreenShot.raw

Status: Deprecated
Removal: 11.0

Use bgra instead.

# Before
data = screenshot.raw

# After
data = screenshot.bgra

Important differences:

• raw is mutable
• bgra is immutable

In 11.0, screenshot pixel buffers will no longer support in-place modification.

If your application relies on modifying screenshot pixels directly, please open an issue so we can discuss your use case.

Screenshot Class Changes

To prepare for future GPU capture support, the screenshot class hierarchy will change in 11.0.

ScreenShot will become a base class with specialized implementations:

ScreenShot
 └── ScreenShotCPU

In preparation for this change, 10.2.0 introduces ScreenShotCPU as a subclass of the current ScreenShot class.

Users who rely on type annotations can begin migrating now:

foo: mss.ScreenShotCPU = sct.grab()

This annotation works in both 10.2.x and 11.x.

If you do not use explicit type annotations, no changes are required.

Monitor Objects

In 11.0, monitor dictionaries will become a dedicated Monitor class.

To maintain compatibility:

• dictionary-style access will continue to work

monitor["left"]
monitor["top"]

• grab() will continue accepting dictionaries

If you use type annotations, you can switch to the provided Monitor type:

from mss.models import Monitor

This works in both 10.2.x and 11.x.

bgra Return Type

In 11.0, ScreenShot.bgra will return a bytes-like object, not necessarily a bytes instance.

Code that treats the result as binary data will continue to work.

If your code checks for an exact type, update it to accept bytes-like objects:

isinstance(data, (bytes, bytearray, memoryview))

cls_image Constructor Behavior

The constructor signature used when providing a custom screenshot class via cls_image may change in 11.0.

If you implement a custom class, ensure your constructor accepts flexible arguments:

def __init__(self, *args, **kwargs):

If you do not use cls_image, you are unaffected.

Internal Platform Attributes

The following attributes were never intended as public API and will be removed in 11.0.

If you need these system libraries, load them directly via ctypes.

Windows

• mss.windows.MSS.user32
• mss.windows.MSS.gdi32

macOS

• mss.darwin.MSS.max_displays

Most users are not affected.

If you believe an upcoming change could impact your workflow, please open an issue so we can discuss it before 11.0.

Full Changelog: v10.1.0...v10.2.0