Install & Compatibility
Where this runs
tested against v10.2.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.028s · 18.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.022s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
MSS
✓ from mss import MSS
✗ import mss; mss.mss()
The `mss.mss()` (lowercase) usage is deprecated starting from v10.2.0. The recommended pattern is `from mss import MSS` and then `with MSS() as sct:`.
This quickstart captures a screenshot of the primary monitor (typically `sct.monitors[1]`, as `sct.monitors[0]` often represents all monitors combined) and saves it as a PNG file using `mss.tools.to_png`.
from mss import MSS
import mss.tools
# Take a screenshot of the primary monitor
with MSS() as sct:
# Get information of monitor 1
monitor_info = sct.monitors[1]
# Grab the data
sct_img = sct.grab(monitor_info)
# Save to the picture file
mss.tools.to_png(sct_img.rgb, sct_img.size, output="screenshot.png")
print("Screenshot saved to screenshot.png")
Debug
Known issues
breakingPython 3.8 support was removed in `v10.0.0`. Ensure your project uses Python 3.9 or newer.fixUpgrade Python to 3.9+ or pin `mss` to `<10.0.0`.
affects: >=10.0.0
breakingPython 3.6 and 3.7 support were removed in `v8.0.0`. Ensure your project uses Python 3.8 or newer for older versions, or 3.9+ for current.fixUpgrade Python to 3.8+ (for v8.x-9.x) or 3.9+ (for v10.x+) or pin `mss` to `<8.0.0`.
affects: >=8.0.0
breakingOn macOS, `v10.1.0` changed the default behavior to take screenshots at nominal resolution (scaling is off). This significantly improves performance. If you require scaled screenshots, set `mss.darwin.IMAGE_OPTIONS = 0` before capturing.fixTo re-enable scaling on macOS, add `mss.darwin.IMAGE_OPTIONS = 0` to your code before instantiating MSS.
affects: >=10.1.0
deprecatedThe `mss.mss()` (lowercase) instantiation, though still functional in `v10.1.0`, is formally deprecated in `v10.2.0`. The recommended practice is to use `from mss import MSS` and then `with MSS() as sct:`.fixUpdate your imports from `import mss` and `mss.mss()` to `from mss import MSS` and `MSS()`.
affects: >=10.2.0 (deprecated in)
gotchaFor intensive use (e.g., in a loop), always reuse the `MSS` instance within a single `with` statement. Creating a new `MSS()` instance in each iteration is highly inefficient and memory-intensive.fixInstantiate `MSS` once using `with MSS() as sct:` outside the loop, then call `sct.grab()` inside the loop.
affects: All versions
gotchaMonitor indexing starts at `0`. `sct.monitors[0]` typically represents the entire virtual screen (all monitors combined), while `sct.monitors[1]` usually corresponds to the first individual physical monitor. Be mindful of this when selecting specific displays.fixAlways inspect `sct.monitors` to understand your system's monitor layout and select the correct index for individual screens.
affects: All versions
gotchaSome other libraries (e.g., `mouseinfo`, `pyautogui`, `pyscreeze`) may incorrectly call `SetProcessDpiAware()` during their import process, leading to scaling/high DPI issues with `mss` on external monitors. To prevent this, import `mss` first.fixEnsure `import mss` is executed before importing any potentially conflicting libraries like `mouseinfo`, `pyautogui`, or `pyscreeze`.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'mss'
The 'mss' library is not installed in the current Python environment, the Python interpreter being used by the IDE/script is not the one where 'mss' is installed, or the script file is named 'mss.py' creating a name conflict.
fixInstall the library using 'pip install mss'. If using a virtual environment, activate it first. If your script is named 'mss.py', rename it to avoid conflict with the library name. Ensure your IDE or command line uses the correct Python interpreter where 'mss' is installed.
mss.exception.ScreenShotError: XGetImage() failed
This error typically occurs on Linux systems when MSS cannot access the display server (e.g., running in a headless environment without an X server, or using Wayland where MSS might expect X11), or when attempting to capture coordinates outside the screen boundaries.
fixEnsure the 'DISPLAY' environment variable is set correctly. For headless environments, use 'Xvfb' (e.g., 'Xvfb :1 -screen 0 1024x768x16 & export DISPLAY=:1'). If on Wayland, try switching to an X11 session or ensuring compatibility. Verify that the capture region coordinates are valid and within the screen dimensions.
AttributeError: '_thread._local' object has no attribute 'srcdc'
MSS instances are not thread-safe and should not be shared directly across multiple threads. Internal resources like device contexts (DCs) are specific to the thread that initialized them, leading to an AttributeError when accessed from a different thread.
fixCreate a new 'mss.mss()' instance within each thread that needs to take a screenshot, rather than trying to share a single instance across threads.
AttributeError: 'MSS' object has no attribute 'grab'
This error often occurs when trying to call 'grab' directly on the 'mss' module itself or an incorrectly initialized instance, or if the 'mss' object is misused, sometimes related to threading issues where the object's state is corrupted.
fixEnsure you are calling 'grab' on an instantiated object of 'mss.mss()', typically within a 'with' statement for proper resource management: 'with mss.mss() as sct: sct_img = sct.grab(monitor_definition)'. If using threads, ensure each thread has its own 'mss.mss()' instance.
libXrandr.so.2: cannot open shared object file: No such file or directory
A required shared library for MSS on Linux, 'libXrandr.so.2', which handles display sizing and arrangement, is missing from the system.
fixInstall the necessary XRandr development package using your system's package manager. For Debian/Ubuntu-based systems: 'sudo apt-get update && sudo apt-get install libxrandr-dev'. For Red Hat/Fedora-based systems: 'sudo yum install libXrandr-devel' or 'sudo dnf install libXrandr-devel'.
Upgrade
Version history
10.2.0latest on PyPI · released Apr 23, 2026
Audit
Dependencies
PillowoptionalCommonly used for image manipulation and saving to various formats after capture, though not strictly required by MSS for capturing.
NumpyoptionalOften used for converting captured images into NumPy arrays for scientific computing or integration with OpenCV.
OpenCVoptionalUsed for advanced image processing and computer vision tasks with captured frames.