MSS (Multiple Screenshots)

10.1.0 · active · verified Fri Apr 10

MSS is an ultra-fast, cross-platform Python module for taking screenshots, built purely in Python using ctypes. It supports Windows, macOS, and Linux, and is optimized for speed, offering multi-monitor and thread-safe capabilities. The library is actively maintained with frequent releases, currently at version 10.1.0, and often integrates with other image processing libraries like Pillow, NumPy, and OpenCV for advanced manipulation.

Warnings

breaking Python 3.8 support was removed in `v10.0.0`. Ensure your project uses Python 3.9 or newer.
Fix: Upgrade Python to 3.9+ or pin `mss` to `<10.0.0`.
breaking Python 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.
Fix: Upgrade Python to 3.8+ (for v8.x-9.x) or 3.9+ (for v10.x+) or pin `mss` to `<8.0.0`.
breaking On 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.
Fix: To re-enable scaling on macOS, add `mss.darwin.IMAGE_OPTIONS = 0` to your code before instantiating MSS.
deprecated The `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:`.
Fix: Update your imports from `import mss` and `mss.mss()` to `from mss import MSS` and `MSS()`.
gotcha For 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.
Fix: Instantiate `MSS` once using `with MSS() as sct:` outside the loop, then call `sct.grab()` inside the loop.
gotcha Monitor 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.
Fix: Always inspect `sct.monitors` to understand your system's monitor layout and select the correct index for individual screens.
gotcha Some 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.
Fix: Ensure `import mss` is executed before importing any potentially conflicting libraries like `mouseinfo`, `pyautogui`, or `pyscreeze`.

Install

pip install mss Install stable version

Imports

MSS
```
from mss import 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:`.

Quickstart

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")

view raw JSON →