feat(linux): Implement an XShmGetImage-based backend (#431)

* Add XCB MIT-SHM support, and factor out the XCB setup

This only adds the support for the XCB MIT-SHM extension to mss's
internal xcb libraries. The actual usage of shared memory for
screenshots will be done in a future commit.

* Implement an XShmGetImage-based backend.

This is close to complete, but there's a few things that need to be
chased down: notably, the test_thread_safety test is failing, for some
reason.  It also currently doesn't work correctly if the root window
size increases.

That said, this is quite promising: on my computer, the new backend
can take 4k screenshots at 30-34 fps, while the XGetImage backend
could only run at 11-14 fps.

* Expand the xcb-util-errors test to include xshmgetimage

* Track down the closed memfd.

Previously, I had been trying to close the memfd in _shutdown_shm, and
ignoring EBADF.  It turns out that XCB will close the memfd when you
send it to the X server.

I think this was one potential cause of the issues I saw in
test_thread_safety: the two threads would be reallocated each others'
fds, leading to thread A closing an fd that thread B was using,
thinking that it was thread A's memfd.

Fix so that the memfd is only explicitly closed in an error situation.

* Ensure that an X11 connection is open during the test session.

Under X11, when the last client disconnects, the server resets.  If
a new client tries to connect before the reset is complete, it may fail.
Since we often run the tests under Xvfb, they're frequently the only
clients.  Since our tests run in rapid succession, this combination
can lead to intermittent failures.

To avoid this, we open a connection at the start of the test session
and keep it open until the end.

* Update the docs

Also, before marking XShmGetImage as unavailable if the first grab()
fails, also test to see if the fallback XGetImage also fails (such as
if the user gave an out-of-bounds rect).  In that case, just reraise
the exception and try XShmGetImage again with the next grab().

* Changes that should have been in the previous commit

* Change the default backend on Linux to xshmgetimage

Also, fix a minor error in the docs formatting.

* Add a --backend argument to the CLI

Author: jholveck

CHANGELOG.md

@@ -5,7 +5,8 @@ See Git checking messages for full history.
 ## 10.1.1.dev0 (2025-xx-xx)
 - Linux: check the server for Xrandr support version (#417)
 - Linux: improve typing and error messages for X libraries (#418)
-- Linux: add a new XCB backend for better thread safety, error-checking, and future development (#425)
+- Linux: introduce an XCB-powered backend stack with a factory in ``mss.linux`` while keeping the Xlib code as a fallback (#425)
+- Linux: add the XShmGetImage backend with automatic XGetImage fallback and explicit status reporting (#431)
 - :heart: contributors: @jholveck
 
 ## 10.1.0 (2025-08-16)

CHANGES.md

@@ -1,5 +1,19 @@
 # Technical Changes
 
+## 10.1.1 (2025-xx-xx)
+
+### linux/__init__.py
+- Added an ``mss()`` factory to select between the different GNU/Linux backends.
+
+### linux/xlib.py
+- Moved the legacy Xlib backend into the ``mss.linux.xlib`` module to be used as a fallback implementation.
+
+### linux/xgetimage.py
+- Added an XCB-based backend that mirrors XGetImage semantics.
+
+### linux/xshmgetimage.py
+- Added an XCB backend powered by XShmGetImage with ``shm_status`` and ``shm_fallback_reason`` attributes for diagnostics.
+
 ## 10.1.0 (2025-08-16)
 
 ### darwin.py

docs/source/api.rst

@@ -33,6 +33,36 @@ GNU/Linux
 
 .. module:: mss.linux
 
+Factory function to return the appropriate backend implementation.
+
+.. function:: mss(backend="default", **kwargs)
+
+    :keyword str backend: Backend name ("default", "xlib", "xgetimage", or "xshmgetimage").
+    :keyword display: Display name (e.g., ":0.0") for the X server.  Default is taken from the :envvar:`DISPLAY` environment variable.
+    :type display: str or None
+    :param kwargs: Additional arguments passed to the backend MSS class.
+    :rtype: :class:`mss.base.MSSBase`
+    :return: Backend-specific MSS instance.
+
+    Factory returning a proper MSS class instance for GNU/Linux.
+    The backend parameter selects the implementation:
+
+    - "default" or "xshmgetimage": XCB-based backend using XShmGetImage (default, with automatic fallback to XGetImage)
+    - "xgetimage": XCB-based backend using XGetImage
+    - "xlib": Traditional Xlib-based backend retained for environments without working XCB libraries
+
+.. function:: MSS(*args, **kwargs)
+
+    Alias for :func:`mss` for backward compatibility.
+
+
+Xlib Backend
+^^^^^^^^^^^^
+
+.. module:: mss.linux.xlib
+
+Legacy Xlib-based backend, kept as a fallback when XCB is unavailable.
+
 .. attribute:: CFUNCTIONS
 
     .. versionadded:: 6.1.0
@@ -79,6 +109,55 @@ GNU/Linux
 
         .. versionadded:: 8.0.0
 
+
+XGetImage Backend
+^^^^^^^^^^^^^^^^^
+
+.. module:: mss.linux.xgetimage
+
+XCB-based backend using XGetImage protocol.
+
+.. class:: MSS
+
+    XCB implementation using XGetImage for screenshot capture.
+
+
+XShmGetImage Backend
+^^^^^^^^^^^^^^^^^^^^
+
+.. module:: mss.linux.xshmgetimage
+
+XCB-based backend using XShmGetImage protocol with shared memory.
+
+.. class:: ShmStatus
+
+    Enum describing the availability of the X11 MIT-SHM extension used by the backend.
+
+    .. attribute:: UNKNOWN
+
+        Initial state before any capture confirms availability or failure.
+
+    .. attribute:: AVAILABLE
+
+        Shared-memory capture works and will continue to be used.
+
+    .. attribute:: UNAVAILABLE
+
+        Shared-memory capture failed; MSS will use XGetImage.
+
+.. class:: MSS
+
+    XCB implementation using XShmGetImage for screenshot capture.
+    Falls back to XGetImage if shared memory extension is unavailable.
+
+    .. attribute:: shm_status
+
+        Current shared-memory availability, using :class:`mss.linux.xshmgetimage.ShmStatus`.
+
+    .. attribute:: shm_fallback_reason
+
+        Optional string describing why the backend fell back to XGetImage when MIT-SHM is unavailable.
+
 Windows
 -------
 

docs/source/developers.rst

@@ -50,3 +50,12 @@ To build the documentation, simply type::
 
     $ python -m pip install -e '.[docs]'
     $ sphinx-build -d docs docs/source docs_out --color -W -bhtml
+
+
+XCB Code Generator
+==================
+
+The GNU/Linux XCB backends rely on generated ctypes bindings.  If you need to
+add new XCB requests or types, do **not** edit ``src/mss/linux/xcbgen.py`` by
+hand.  Instead, follow the workflow described in ``src/xcbproto/README.md``,
+which explains how to update ``gen_xcb_to_py.py`` and regenerate the bindings.

docs/source/examples.rst

@@ -103,6 +103,15 @@ You can handle data using a custom class:
 
 .. versionadded:: 3.1.0
 
+GNU/Linux XShm backend
+----------------------
+
+Select the XShmGetImage backend explicitly and inspect whether it is active or
+falling back to XGetImage:
+
+.. literalinclude:: examples/linux_xshm_backend.py
+    :lines: 7-
+
 PIL
 ===
 

docs/source/examples/linux_xshm_backend.py

@@ -0,0 +1,17 @@
+"""This is part of the MSS Python's module.
+Source: https://github.com/BoboTiG/python-mss.
+
+Select the XShmGetImage backend explicitly and inspect its status.
+"""
+
+from mss.linux.xshmgetimage import MSS as mss
+
+with mss() as sct:
+    screenshot = sct.grab(sct.monitors[1])
+    print(f"Captured screenshot dimensions: {screenshot.size.width}x{screenshot.size.height}")
+
+    print(f"shm_status: {sct.shm_status.name}")
+    if sct.shm_fallback_reason:
+        print(f"Falling back to XGetImage because: {sct.shm_fallback_reason}")
+    else:
+        print("MIT-SHM capture active.")

docs/source/usage.rst

@@ -5,7 +5,7 @@ Usage
 Import
 ======
 
-So MSS can be used as simply as::
+MSS can be used as simply as::
 
     from mss import mss
 
@@ -20,6 +20,11 @@ Or import the good one based on your operating system::
     # Microsoft Windows
     from mss.windows import MSS as mss
 
+On GNU/Linux you can also import a specific backend (see :ref:`backends`)
+directly when you need a particular implementation, for example::
+
+    from mss.linux.xshmgetimage import MSS as mss
+
 
 Instance
 ========
@@ -49,18 +54,56 @@ This is a much better usage, memory efficient::
 Also, it is a good thing to save the MSS instance inside an attribute of your class and calling it when needed.
 
 
+.. _backends:
+
+Backends
+--------
+
+Some platforms have multiple ways to take screenshots.  In MSS, these are known as *backends*.  The :py:func:`mss` functions will normally autodetect which one is appropriate for your situation, but you can override this if you want.  For instance, you may know that your specific situation requires a particular backend.
+
+If you want to choose a particular backend, you can use the :py::`backend` keyword to :py:func:`mss`::
+
+    with mss(backend="xgetimage") as sct:
+        ...
+
+Alternatively, you can also directly import the backend you want to use::
+
+    from mss.linux.xgetimage import MSS as mss
+
+Currently, only the GNU/Linux implementation has multiple backends.  These are described in their own section below.
+
+
 GNU/Linux
 ---------
 
-On GNU/Linux, you can specify which display to use (useful for distant screenshots via SSH)::
-
-    with mss(display=":0.0") as sct:
-        # ...
+Display
+^^^^^^^
 
-A more specific example (only valid on GNU/Linux):
+On GNU/Linux, the default display is taken from the :envvar:`DISPLAY` environment variable.  You can instead specify which display to use (useful for distant screenshots via SSH) using the ``display`` keyword:
 
 .. literalinclude:: examples/linux_display_keyword.py
-    :lines: 9-
+    :lines: 7-
+
+
+Backends
+^^^^^^^^
+
+The GNU/Linux implementation has multiple backends (see :ref:`backends`), or ways it can take screenshots.  The :py:func:`mss.mss` and :py:func:`mss.linux.mss` functions will normally autodetect which one is appropriate, but you can override this if you want.
+
+There are three available backends.
+
+:py:mod:`xshmgetimage` (default)
+    The fastest backend, based on :c:func:`xcb_shm_get_image`.  It is roughly three times faster than :py:mod:`xgetimage`
+    and is used automatically.  When the MIT-SHM extension is unavailable (for example on remote SSH displays), it
+    transparently falls back to :py:mod:`xgetimage` so you can always request it safely.
+
+:py:mod:`xgetimage`
+    A highly-compatible, but slower, backend based on :c:func:`xcb_get_image`.  Use this explicitly only when you know
+    that :py:mod:`xshmgetimage` cannot operate in your environment.
+
+:py:mod:`xlib`
+    The legacy backend powered by :c:func:`XGetImage`.  It is kept solely for systems where XCB libraries are
+    unavailable and no new features are being added to it.
 
 
 Command Line
@@ -73,8 +116,8 @@ You can use ``mss`` via the CLI::
 Or via direct call from Python::
 
     $ python -m mss --help
-    usage: __main__.py [-h] [-c COORDINATES] [-l {0,1,2,3,4,5,6,7,8,9}]
-                    [-m MONITOR] [-o OUTPUT] [-q] [-v] [--with-cursor]
+    usage: mss [-h] [-c COORDINATES] [-l {0,1,2,3,4,5,6,7,8,9}] [-m MONITOR]
+           [-o OUTPUT] [--with-cursor] [-q] [-b BACKEND] [-v]
 
     options:
     -h, --help            show this help message and exit
@@ -86,6 +129,9 @@ Or via direct call from Python::
                           the monitor to screenshot
     -o OUTPUT, --output OUTPUT
                           the output file name
+    -b, --backend BACKEND
+                          platform-specific backend to use
+                          (Linux: default/xlib/xgetimage/xshmgetimage; macOS/Windows: default)
     --with-cursor         include the cursor
     -q, --quiet           do not print created files
     -v, --version         show program's version number and exit

pyproject.toml

@@ -179,6 +179,7 @@ ignore = [
 "docs/source/*" = [
   "ERA001",   # commented code
   "INP001",   # file `xxx` is part of an implicit namespace package
+  "N811",     # importing constant (MSS) as non-constant (mss)
 ]
 "src/tests/*" = [
   "FBT001",   # boolean-typed positional argument in function definition

src/mss/__main__.py

@@ -3,18 +3,38 @@
 """
 
 import os.path
+import platform
 import sys
-from argparse import ArgumentParser
+from argparse import ArgumentError, ArgumentParser
 
 from mss import __version__
 from mss.exception import ScreenShotError
 from mss.factory import mss
 from mss.tools import to_png
 
 
+def _backend_cli_choices() -> list[str]:
+    os_name = platform.system().lower()
+    if os_name == "darwin":
+        from mss import darwin  # noqa: PLC0415
+
+        return list(darwin.BACKENDS)
+    if os_name == "linux":
+        from mss import linux  # noqa: PLC0415
+
+        return list(linux.BACKENDS)
+    if os_name == "windows":
+        from mss import windows  # noqa: PLC0415
+
+        return list(windows.BACKENDS)
+    return ["default"]
+
+
 def main(*args: str) -> int:
     """Main logic."""
-    cli_args = ArgumentParser(prog="mss")
+    backend_choices = _backend_cli_choices()
+
+    cli_args = ArgumentParser(prog="mss", exit_on_error=False)
     cli_args.add_argument(
         "-c",
         "--coordinates",
@@ -40,9 +60,19 @@ def main(*args: str) -> int:
         action="store_true",
         help="do not print created files",
     )
+    cli_args.add_argument(
+        "-b", "--backend", default="default", choices=backend_choices, help="platform-specific backend to use"
+    )
     cli_args.add_argument("-v", "--version", action="version", version=__version__)
 
-    options = cli_args.parse_args(args or None)
+    try:
+        options = cli_args.parse_args(args or None)
+    except ArgumentError as e:
+        # By default, parse_args will print and the error and exit.  We
+        # return instead of exiting, to make unit testing easier.
+        cli_args.print_usage(sys.stderr)
+        print(f"{cli_args.prog}: error: {e}", file=sys.stderr)
+        return 2
     kwargs = {"mon": options.monitor, "output": options.output}
     if options.coordinates:
         try:
@@ -61,7 +91,7 @@ def main(*args: str) -> int:
             kwargs["output"] = "sct-{top}x{left}_{width}x{height}.png"
 
     try:
-        with mss(with_cursor=options.with_cursor) as sct:
+        with mss(with_cursor=options.with_cursor, backend=options.backend) as sct:
             if options.coordinates:
                 output = kwargs["output"].format(**kwargs["mon"])
                 sct_img = sct.grab(kwargs["mon"])

src/mss/base.py

@@ -18,6 +18,15 @@
 
     from mss.models import Monitor, Monitors
 
+    # Prior to 3.11, Python didn't have the Self type.  typing_extensions does, but we don't want to depend on it.
+    try:
+        from typing import Self
+    except ImportError:  # pragma: nocover
+        try:
+            from typing_extensions import Self
+        except ImportError:  # pragma: nocover
+            Self = Any  # type: ignore[assignment]
+
 try:
     from datetime import UTC
 except ImportError:  # pragma: nocover
@@ -58,7 +67,7 @@ def __init__(
             msg = 'The only valid backend on this platform is "default".'
             raise ScreenShotError(msg)
 
-    def __enter__(self) -> MSSBase:  # noqa:PYI034
+    def __enter__(self) -> Self:
         """For the cool call `with MSS() as mss:`."""
         return self