How to Take Screenshots with Python MSS

Python MSS stands for Multiple Screen Shot, and it lives up to the name. It handles multi-monitor setups natively, runs on Windows, macOS, and Linux, and delivers solid performance.

If you want to save time, I shared all the code examples in the open GitHub repository.

Installation and Basic Usage

Install the library using pip:

1
pip install mss

And then:

1
import mss
2

3
with mss.mss() as sct:
4
    # Capture the first monitor
5
    screenshot = sct.grab(sct.monitors[1])
6

7
    # Save to file
8
    mss.tools.to_png(screenshot.rgb, screenshot.size, output='screenshot.png')

Understanding Monitors

mss uses an index system for monitors:

1
import mss
2

3
with mss.mss() as sct:
4
    # monitors[0] = all monitors combined
5
    # monitors[1] = first monitor
6
    # monitors[2] = second monitor (if exists)
7

8
    for i, monitor in enumerate(sct.monitors):
9
        print(f"Monitor {i}: {monitor}")

Output:

1
Monitor 0: {'left': 0, 'top': 0, 'width': 3840, 'height': 1080}
2
Monitor 1: {'left': 0, 'top': 0, 'width': 1920, 'height': 1080}
3
Monitor 2: {'left': 1920, 'top': 0, 'width': 1920, 'height': 1080}

Capturing Specific Monitors

1
import mss
2

3
with mss.mss() as sct:
4
    # First monitor
5
    first_monitor = sct.grab(sct.monitors[1])
6

7
    # Second monitor
8
    second_monitor = sct.grab(sct.monitors[2])
9

10
    # All monitors combined
11
    all_monitors = sct.grab(sct.monitors[0])

Capturing Specific Regions

Define a region with a dictionary:

1
import mss
2

3
with mss.mss() as sct:
4
    region = {
5
        'left': 100,    # X coordinate
6
        'top': 100,     # Y coordinate
7
        'width': 500,   # Width in pixels
8
        'height': 500   # Height in pixels
9
    }
10

11
    screenshot = sct.grab(region)
12
    mss.tools.to_png(screenshot.rgb, screenshot.size, output='region.png')

Saving Screenshots

To PNG File

1
import mss
2

3
with mss.mss() as sct:
4
    screenshot = sct.grab(sct.monitors[1])
5
    mss.tools.to_png(screenshot.rgb, screenshot.size, output='screenshot.png')

To PIL Image

1
import mss
2
from PIL import Image
3

4
with mss.mss() as sct:
5
    screenshot = sct.grab(sct.monitors[1])
6

7
    # Convert BGRA to RGB
8
    img = Image.frombytes('RGB', screenshot.size, screenshot.bgra, 'raw', 'BGRX')
9
    img.save('screenshot.png')

To NumPy Array

1
import mss
2
import numpy as np
3

4
with mss.mss() as sct:
5
    screenshot = sct.grab(sct.monitors[1])
6
    img_array = np.array(screenshot)  # BGRA format
7

8
    # Convert to RGB if needed
9
    rgb_array = img_array[:, :, :3][:, :, ::-1]  # Remove alpha, BGR to RGB

Understanding Color Formats

mss returns BGRA (Blue, Green, Red, Alpha) format:

1
import mss
2

3
with mss.mss() as sct:
4
    screenshot = sct.grab(sct.monitors[1])
5

6
    # Raw bytes (BGRA)
7
    bgra_bytes = screenshot.bgra
8

9
    # RGB bytes (for saving)
10
    rgb_bytes = screenshot.rgb
11

12
    # Size tuple
13
    width, height = screenshot.size

BGRA to RGB Conversion

1
import mss
2
import numpy as np
3

4
with mss.mss() as sct:
5
    screenshot = sct.grab(sct.monitors[1])
6

7
    # Method 1: Using numpy
8
    bgra = np.array(screenshot)
9
    rgb = bgra[:, :, [2, 1, 0]]  # Swap B and R channels
10

11
    # Method 2: Using PIL
12
    from PIL import Image
13
    img = Image.frombytes('RGB', screenshot.size, screenshot.bgra, 'raw', 'BGRX')

Performance Optimization

Reuse the mss Instance

1
import mss
2

3
# Bad: Creating new instance each time
4
for i in range(100):
5
    with mss.mss() as sct:
6
        screenshot = sct.grab(sct.monitors[1])
7

8
# Good: Reuse instance
9
with mss.mss() as sct:
10
    for i in range(100):
11
        screenshot = sct.grab(sct.monitors[1])

Capture Only What You Need

1
import mss
2

3
with mss.mss() as sct:
4
    # Capturing a smaller region is faster
5
    small_region = {'left': 0, 'top': 0, 'width': 100, 'height': 100}
6
    screenshot = sct.grab(small_region)

Benchmark

1
import mss
2
import time
3

4
with mss.mss() as sct:
5
    monitor = sct.monitors[1]
6

7
    start = time.time()
8
    frames = 0
9

10
    while time.time() - start < 5:
11
        sct.grab(monitor)
12
        frames += 1
13

14
    fps = frames / 5
15
    print(f"FPS: {fps:.1f}")

Typical results: 30-60 FPS depending on resolution and system.

Continuous Capture

1
import mss
2
import time
3

4
def record_screen(duration_seconds, output_dir='frames'):
5
    import os
6
    os.makedirs(output_dir, exist_ok=True)
7

8
    frames = []
9

10
    with mss.mss() as sct:
11
        monitor = sct.monitors[1]
12
        start = time.time()
13

14
        while time.time() - start < duration_seconds:
15
            screenshot = sct.grab(monitor)
16
            frames.append(screenshot)
17

18
    # Save frames
19
    for i, frame in enumerate(frames):
20
        mss.tools.to_png(frame.rgb, frame.size, output=f'{output_dir}/frame_{i:05d}.png')
21

22
    print(f"Captured {len(frames)} frames")
23
    return frames
24

25
record_screen(2)  # Record 2 seconds

Common Errors and Solutions

ScreenShotError: xgetimage() failed

This error occurs on Linux when the X display isn’t accessible.

Solution 1: Set the DISPLAY variable

1
export DISPLAY=:0
2
python your_script.py

Solution 2: Use Xvfb for headless servers

1
apt-get install xvfb
2
xvfb-run python your_script.py

Solution 3: Check display access in code

1
import os
2
import mss
3

4
# Ensure DISPLAY is set
5
if 'DISPLAY' not in os.environ:
6
    os.environ['DISPLAY'] = ':0'
7

8
with mss.mss() as sct:
9
    screenshot = sct.grab(sct.monitors[1])

Import Error on Linux

1
# Install required system dependencies
2
apt-get install python3-xlib

MSS vs DXcam

Feature	MSS	DXcam
Platform	Windows, macOS, Linux	Windows only
FPS	30-60	240+
Multi-monitor	Excellent	Good
Dependencies	Pure Python	DirectX
Best for	Cross-platform	Gaming

Use MSS when: You need cross-platform support or don’t need extreme performance.

Use DXcam when: You are on Windows and need maximum FPS.

However, consider that DXcam is not actively maintained at the moment of writing the guide.

Complete Example

1
import mss
2
import time
3
from PIL import Image
4
from pathlib import Path
5

6
class ScreenCapture:
7
    def __init__(self, output_dir='captures'):
8
        self.output_dir = Path(output_dir)
9
        self.output_dir.mkdir(exist_ok=True)
10

11
    def capture_monitor(self, monitor_index=1, filename='screenshot.png'):
12
        """Capture a specific monitor."""
13
        with mss.mss() as sct:
14
            if monitor_index >= len(sct.monitors):
15
                raise ValueError(f"Monitor {monitor_index} not found")
16

17
            screenshot = sct.grab(sct.monitors[monitor_index])
18
            output_path = self.output_dir / filename
19
            mss.tools.to_png(screenshot.rgb, screenshot.size, output=str(output_path))
20
            return output_path
21

22
    def capture_region(self, left, top, width, height, filename='region.png'):
23
        """Capture a specific region."""
24
        region = {'left': left, 'top': top, 'width': width, 'height': height}
25

26
        with mss.mss() as sct:
27
            screenshot = sct.grab(region)
28
            output_path = self.output_dir / filename
29
            mss.tools.to_png(screenshot.rgb, screenshot.size, output=str(output_path))
30
            return output_path
31

32
    def list_monitors(self):
33
        """List available monitors."""
34
        with mss.mss() as sct:
35
            return sct.monitors
36

37
# Usage
38
capture = ScreenCapture()
39
print("Monitors:", capture.list_monitors())
40
capture.capture_monitor(1, 'monitor1.png')
41
capture.capture_region(0, 0, 500, 500, 'region.png')

Run the script with:

1
python record_screen.py

Results on my machine:

For the first monitor: Monitor screenshot by Python MSS library

For the region: Region screenshot by Python MSS library

Summary

Python MSS is the best general-purpose screen capture library for Python:

Cross-platform (Windows, macOS, Linux)
Fast enough for most use cases (30-60 FPS)
Native multi-monitor support
Simple API with no complex dependencies

For website screenshots check out our guide on website screenshots with Python or use Playwright.

Frequently Asked Questions

If you read the article, but still have questions. Please, check the most frequently asked. And if you still have questions, feel free reach out at support@screenshotone.com.

Is MSS faster than DXcam for screen capture?

No, DXcam is faster (240+ FPS vs 30-60 FPS), but it only works on Windows. mss is the best choice for cross-platform code or when you don't need extreme performance.

How to fix MSS ScreenShotError xgetimage() failed?

This error occurs on Linux when the display isn't accessible. Make sure DISPLAY environment variable is set, or run with a display server. For headless servers, use Xvfb.

What format does MSS grab() return?

MSS returns a ScreenShot object with BGRA pixel data. Use screenshot.rgb for RGB data, or convert with PIL/numpy for other formats.

How to Take Screenshots with Python MSS

Written by

Published on

Tags