{"id":2597,"library":"mss","title":"MSS (Multiple Screenshots)","description":"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.","status":"active","version":"10.1.0","language":"en","source_language":"en","source_url":"https://github.com/BoboTiG/python-mss","tags":["screenshot","screen capture","image","cross-platform","ctypes","performance"],"install":[{"cmd":"pip install mss","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Commonly used for image manipulation and saving to various formats after capture, though not strictly required by MSS for capturing.","package":"Pillow","optional":true},{"reason":"Often used for converting captured images into NumPy arrays for scientific computing or integration with OpenCV.","package":"Numpy","optional":true},{"reason":"Used for advanced image processing and computer vision tasks with captured frames.","package":"OpenCV","optional":true}],"imports":[{"note":"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:`.","wrong":"import mss; mss.mss()","symbol":"MSS","correct":"from mss import MSS"}],"quickstart":{"code":"from mss import MSS\nimport mss.tools\n\n# Take a screenshot of the primary monitor\nwith MSS() as sct:\n    # Get information of monitor 1\n    monitor_info = sct.monitors[1]\n    \n    # Grab the data\n    sct_img = sct.grab(monitor_info)\n    \n    # Save to the picture file\n    mss.tools.to_png(sct_img.rgb, sct_img.size, output=\"screenshot.png\")\n    print(\"Screenshot saved to screenshot.png\")\n","lang":"python","description":"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`."},"warnings":[{"fix":"Upgrade Python to 3.9+ or pin `mss` to `<10.0.0`.","message":"Python 3.8 support was removed in `v10.0.0`. Ensure your project uses Python 3.9 or newer.","severity":"breaking","affected_versions":">=10.0.0"},{"fix":"Upgrade Python to 3.8+ (for v8.x-9.x) or 3.9+ (for v10.x+) or pin `mss` to `<8.0.0`.","message":"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.","severity":"breaking","affected_versions":">=8.0.0"},{"fix":"To re-enable scaling on macOS, add `mss.darwin.IMAGE_OPTIONS = 0` to your code before instantiating MSS.","message":"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.","severity":"breaking","affected_versions":">=10.1.0"},{"fix":"Update your imports from `import mss` and `mss.mss()` to `from mss import MSS` and `MSS()`.","message":"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:`.","severity":"deprecated","affected_versions":">=10.2.0 (deprecated in)"},{"fix":"Instantiate `MSS` once using `with MSS() as sct:` outside the loop, then call `sct.grab()` inside the loop.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always inspect `sct.monitors` to understand your system's monitor layout and select the correct index for individual screens.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure `import mss` is executed before importing any potentially conflicting libraries like `mouseinfo`, `pyautogui`, or `pyscreeze`.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}