Python MSS

https://python-mss.readthedocs.io/
Admin
Python MSS is a fast, cross-platform module to take screenshots of the screen or parts of the...
Tokens:33,096
Snippets:328
Trust Score:8.3
Update:1 week ago
Show doc for...
Tokens:
Raw
### Setup development environment with venv and pip

Source: https://python-mss.readthedocs.io/latest/developers.html

Creates a virtual environment, activates it, upgrades pip, and installs the package with test dependencies. Required before running tests.

```bash
$ python -m venv venv
$ . venv/bin/activate
$ python -m pip install -U pip
$ python -m pip install -e '.[tests]'

```

--------------------------------

### Install MSS from source

Source: https://python-mss.readthedocs.io/latest/installation.html

Install the module from the cloned source using setup.py with the --user flag.

```bash
$ python setup.py install --user

```

--------------------------------

### Install MSS with pip

Source: https://python-mss.readthedocs.io/latest/installation.html

Recommended way to install the mss module using pip. The -U flag upgrades the package if already installed, and --user installs it for the current user only.

```bash
$ python -m pip install -U --user mss

```

--------------------------------

### Build documentation with Sphinx

Source: https://python-mss.readthedocs.io/latest/developers.html

Installs documentation dependencies and builds the HTML documentation with Sphinx. The command outputs to docs_out and treats warnings as errors.

```bash
$ python -m pip install -e '.[docs]'
$ sphinx-build -d docs docs/source docs_out --color -W -bhtml

```

--------------------------------

### Install dev dependencies and run check scripts

Source: https://python-mss.readthedocs.io/latest/developers.html

Installs development dependencies and runs the code quality check script. Use ./check.sh on Linux/macOS and .\check.ps1 on Windows (PowerShell).

```bash
$ python -m pip install -e '.[dev]'
$ ./check.sh  # Linux/macOS
$ .\check.ps1  # Windows (PowerShell)

```

--------------------------------

### Run the test suite with pytest

Source: https://python-mss.readthedocs.io/latest/developers.html

Launches the full test suite using pytest. Run after installing test dependencies.

```bash
$ python -m pytest

```

--------------------------------

### PIL example using to_pil()

Source: https://python-mss.readthedocs.io/latest/examples.html

Use mss.ScreenShot.to_pil() to convert raw pixels to a PIL image and save each monitor as a PNG file. Added in version 3.0.0.

```python
import mss

with mss.MSS() as sct:
    # Get rid of the first, as it represents the "All in One" monitor:
    for num, monitor in enumerate(sct.monitors[1:], 1):
        # Get raw pixels from the screen
        sct_img = sct.grab(monitor)

        # Create the Image
        img = sct_img.to_pil("RGB")

        # And save it!
        output = f"monitor-{num}.png"
        img.save(output)
        print(output)
```

--------------------------------

### Hypothetical gated feature example with MSS

Source: https://python-mss.readthedocs.io/latest/versioning.html

Shows how a new feature could be gated behind an explicit opt-in parameter, such as device="cuda", to return a different screenshot type without affecting existing usage.

```python
with MSS() as sct:
    img = sct.grab(sct.primary_monitor)
    # returns ScreenShotCPU

with MSS(device="cuda") as sct:
    img = sct.grab(sct.primary_monitor)
    # returns ScreenShotCUDA

```

--------------------------------

### Callback example for sct.shot()

Source: https://python-mss.readthedocs.io/latest/examples.html

Shows how to use the callback parameter of sct.shot() to handle existing files. The callback renames an existing screenshot to a .old file before overwriting. Requires an active mss instance.

```python
from pathlib import Path

import mss


def on_exists(fname: str) -> None:
    """Callback example when we try to overwrite an existing screenshot."""
    file = Path(fname)
    if file.is_file():
        newfile = file.with_name(f"{file.name}.old")
        print(f"{fname} → {newfile}")
        file.rename(newfile)


with mss.MSS() as sct:
    filename = sct.shot(output="mon-{mon}.png", callback=on_exists)
    print(filename)

```

--------------------------------

### Install MSS via Conda

Source: https://python-mss.readthedocs.io/latest/installation.html

Install the python-mss package from the conda-forge channel using Conda.

```bash
$ conda install -c conda-forge python-mss

```

--------------------------------

### Capture primary monitor screenshot

Source: https://python-mss.readthedocs.io/latest/usage.html

Use this to capture the primary monitor and get a ScreenShot object. The context manager ensures proper cleanup.

```python
with MSS() as sct:
    sct_img = sct.grab(sct.primary_monitor)

```

--------------------------------

### Convert monitor to region and grab screenshot

Source: https://python-mss.readthedocs.io/latest/usage.html

Call as_region() to get a Region object, adjust its width, and capture a screenshot. This is useful when you need to modify the region before grabbing.

```python
region = monitor.as_region()
region.width -= 1
screenshot = sct.grab(region)

```

--------------------------------

### Access primary monitor dimensions

Source: https://python-mss.readthedocs.io/latest/usage.html

Use this to get the primary monitor and print its width and height. The primary monitor is the one with the taskbar or system UI.

```python
monitor = sct.primary_monitor
print(monitor.width, monitor.height)

```

--------------------------------

### Convert BGRA to RGB with mss_rgb, numpy_flip, numpy_slice, pil_frombuffer

Source: https://python-mss.readthedocs.io/latest/examples.html

Provides four functions to convert raw BGRA screen capture data to RGB: mss_rgb (uses MSS's built-in rgb property), numpy_flip (most efficient Numpy version as of MSS 10.1), numpy_slice (slow Numpy version), and pil_frombuffer (efficient Pillow version). The example ends with a context manager that grabs the first monitor and converts the frame using pil_frombuffer. Requires the mss, numpy, and PIL (Pillow) libraries.

```python
def mss_rgb(im):
    """ Better than Numpy versions, but slower than Pillow. """
    return im.rgb


def numpy_flip(im):
    """ Most efficient Numpy version as of MSS 10.1. """
    frame = numpy.array(im, dtype=numpy.uint8)
    return numpy.flip(frame[:, :, :3], 2).tobytes()


def numpy_slice(im):
    """ Slow Numpy version. """
    return numpy.array(im, dtype=numpy.uint8)[..., [2, 1, 0]].tobytes()


def pil_frombuffer(im):
    """ Efficient Pillow version. """
    return Image.frombuffer('RGB', im.size, im.bgra, 'raw', 'BGRX').tobytes()


with mss.MSS() as sct:
    im = sct.grab(sct.monitors[1])
    rgb = pil_frombuffer(im)
    ...
```

--------------------------------

### Access primary monitor with sct.primary_monitor

Source: https://python-mss.readthedocs.io/latest/release-history/v10.2.0.html

Use the new sct.primary_monitor property to get the monitor dictionary for the primary display. Available on Windows and Linux; macOS support is planned.

```python
sct.primary_monitor
```

--------------------------------

### mss.MSS.monitors property

Source: https://python-mss.readthedocs.io/latest/api.html

Get positions of all monitors. The first element is the virtual desktop, subsequent elements are individual displays.

```APIDOC
## monitors property

### Description
Get positions of all monitors. If a monitor is rotated, its dimensions reflect its displayed orientation. The first element, monitors[0], is all the monitors together (virtual desktop). The remaining elements, monitors[N] (N > 0), are individual displays. If monitors are mirrored, only one copy is included.

### Returns
Monitors - List of monitor information.
```

--------------------------------

### Select a backend with MSS(backend=...)

Source: https://python-mss.readthedocs.io/latest/usage.html

Use the `backend` keyword to force a specific backend, such as `xgetimage`, when the default autodetection is not suitable.

```python
with MSS(backend="xgetimage") as sct:
    ...

```

--------------------------------

### MSS.compression_level

Source: https://python-mss.readthedocs.io/latest/index.html

Property to get or set the compression level for PNG saving.

```APIDOC
## MSS.compression_level

### Description
Property to get or set the compression level for PNG saving.

### Property
`compression_level` (int) - The compression level used when saving PNG screenshots.
```

--------------------------------

### Import MSS and use context manager

Source: https://python-mss.readthedocs.io/latest/usage.html

Use this to import the MSS class and capture screenshots within a context manager. The context manager ensures proper resource cleanup.

```python
from mss import MSS

with MSS() as sct:
    # ...

```

--------------------------------

### mss CLI help

Source: https://python-mss.readthedocs.io/latest/usage.html

Displays the help message for the mss command-line tool, listing all available options and their usage.

```bash
mss --help

```

--------------------------------

### Screenshot of all monitors (fullscreen)

Source: https://python-mss.readthedocs.io/latest/examples.html

Captures the entire virtual screen (all monitors) using mon=-1 and saves it as 'fullscreen.png', printing the filename. Requires an active mss instance (sct).

```python
filename = sct.shot(mon=-1, output='fullscreen.png')
print(filename)

```

--------------------------------

### Take a screenshot of the first monitor with MSS

Source: https://python-mss.readthedocs.io/

The simplest use of the MSS library: create an MSS instance and call shot() to save a screenshot of the first monitor to a PNG file. Requires Python 3.9+ and the mss package.

```python
from mss import MSS

# The simplest use, save a screenshot of the 1st monitor
with MSS() as sct:
    sct.shot()

```

--------------------------------

### ScreenShot.from_size()

Source: https://python-mss.readthedocs.io/latest/index.html

Creates a ScreenShot instance from a given size.

```APIDOC
## ScreenShot.from_size()

### Description
Creates a ScreenShot instance from a given size.

### Method
`from_size(size)`

### Parameters
- **size** (Size) - The size of the screenshot.

### Returns
- **ScreenShot** - A new ScreenShot instance.
```

--------------------------------

### Get PNG bytes, no file output

Source: https://python-mss.readthedocs.io/latest/examples.html

Generates PNG bytes without writing to a file by calling mss.tools.to_png() without an output argument. Requires an active mss instance.

```python
with mss.MSS() as sct:
    # The monitor or screen part to capture
    monitor = sct.monitors[1]  # or a region

    # Grab the data
    sct_img = sct.grab(monitor)

    # Generate the PNG
    png = mss.tools.to_png(sct_img.rgb, sct_img.size)

```

--------------------------------

### python -m mss help output

Source: https://python-mss.readthedocs.io/latest/usage.html

Shows the help output when running mss as a Python module, including all command-line options and their descriptions.

```bash
$ python -m mss --help
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
-c, --coordinates COORDINATES
                      the part of the screen to capture:
                      TOP,LEFT,WIDTH,HEIGHT or WIDTHxHEIGHT+LEFT+TOP
-l, --level {0,1,2,3,4,5,6,7,8,9}
                      the PNG compression level
-m, --monitor MONITOR
                      the monitor to screenshot
-o, --output OUTPUT
                      the output file name
-b, --backend BACKEND
                      platform-specific backend to use
                      (Linux: default/xlib/xgetimage/xshmgetimage; macOS: default; Windows: default/gdi)
--with-cursor         include the cursor
-q, --quiet           do not print created files
-v, --version         show program's version number and exit

```

--------------------------------

### Specify display on GNU/Linux with MSS(display=...)

Source: https://python-mss.readthedocs.io/latest/usage.html

Use the `display` keyword to select a specific X display, useful for distant screenshots via SSH. The default display is taken from the `DISPLAY` environment variable.

```python
import mss

with mss.MSS(display=":0.0") as sct:
    for filename in sct.save():
        print(filename)

```

--------------------------------

### Flexible constructor for custom screenshot class

Source: https://python-mss.readthedocs.io/latest/release-history/v10.2.0.html

Shows the recommended constructor signature for custom screenshot classes passed via `cls_image`, to accommodate potential signature changes in 11.0.

```python
def __init__(self, *args, **kwargs):

```

--------------------------------

### Screenshot of monitor 1

Source: https://python-mss.readthedocs.io/latest/examples.html

Captures the first monitor (monitor 1) and saves it to a file, printing the filename. Requires an active mss instance (sct).

```python
filename = sct.shot()
print(filename)

```

--------------------------------

### Use PIL bbox style and percent values

Source: https://python-mss.readthedocs.io/latest/examples.html

Captures a region using a bbox tuple with percentage-based offsets from the monitor's top-left corner, similar to PIL's ImageGrab. Added in version 3.1.0. Requires an active mss instance.

```python
import mss
import mss.tools

with mss.MSS() as sct:
    # Use the 1st monitor
    monitor = sct.monitors[1]

    # Capture a bbox using percent values
    left = monitor.left + monitor.width * 5 // 100  # 5% from the left
    top = monitor.top + monitor.height * 5 // 100  # 5% from the top
    right = left + 400  # 400px width
    lower = top + 400  # 400px height
    bbox = (left, top, right, lower)

    # Grab the picture
    # Using PIL would be something like:
    # im = ImageGrab(bbox=bbox)
    im = sct.grab(bbox)

    # Save it!
    mss.tools.to_png(im.rgb, im.size, output="screenshot.png")

```

--------------------------------

### mss()

Source: https://python-mss.readthedocs.io/latest/index.html

Factory function to create an MSS instance.

```APIDOC
## mss()

### Description
Factory function to create an MSS instance.

### Method
`mss()`

### Returns
- **MSS** - An MSS instance.
```

--------------------------------

### Good usage: reuse MSS instance

Source: https://python-mss.readthedocs.io/latest/usage.html

Creates one MSS instance and reuses it for all captures, reducing overhead and improving memory efficiency.

```python
with MSS() as sct:
    for _ in range(100):
        sct.shot()

```

--------------------------------

### Monitor.output

Source: https://python-mss.readthedocs.io/latest/support.html

Returns the output of the monitor.

```APIDOC
## `Monitor.output`

### Description
Returns the output of the monitor.
```

--------------------------------

### MSS.grab()

Source: https://python-mss.readthedocs.io/latest/index.html

Captures a screenshot of the specified monitor or region.

```APIDOC
## MSS.grab()

### Description
Captures a screenshot of the specified monitor or region.

### Method
`grab(monitor)`

### Parameters
- **monitor** (dict or Monitor) - The monitor or region to capture.
```

--------------------------------

### mss.MSS.shot()

Source: https://python-mss.readthedocs.io/latest/api.html

Helper to save the screenshot of the 1st monitor by default. Accepts same arguments as save().

```APIDOC
## shot(**kwargs)

### Description
Helper to save the screenshot of the 1st monitor, by default. You can pass the same arguments as for save().

### Parameters
- **kwargs** (Any) - Optional - Same arguments as save().

### Returns
str - The output filename.
```

--------------------------------

### Monitor.name

Source: https://python-mss.readthedocs.io/latest/support.html

Returns the name of the monitor.

```APIDOC
## `Monitor.name`

### Description
Returns the name of the monitor.
```

--------------------------------

### Multiprocessing screen capture with mss.tools.to_png

Source: https://python-mss.readthedocs.io/latest/examples.html

Uses multiprocessing to delegate PNG file creation to a separate worker, improving performance. The grab process captures 1000 screenshots and puts them on a queue; the save process writes them as PNG files using `mss.tools.to_png`. Added in version 5.0.0.

```python
from multiprocessing import Process, Queue

import mss
import mss.tools
from mss.models import Region


def grab(queue: Queue) -> None:
    region = Region(left=0, top=0, width=600, height=800)

    with mss.MSS() as sct:
        for _ in range(1_000):
            queue.put(sct.grab(region))

    # Tell the other worker to stop
    queue.put(None)


def save(queue: Queue) -> None:
    number = 0
    output = "screenshots/file_{}.png"
    to_png = mss.tools.to_png

    while "there are screenshots":
        img = queue.get()
        if img is None:
            break

        to_png(img.rgb, img.size, output=output.format(number))
        number += 1


if __name__ == "__main__":
    # The screenshots queue
    queue: Queue = Queue()

    # 2 processes: one for grabbing and one for saving PNG files
    Process(target=grab, args=(queue,)).start()
    Process(target=save, args=(queue,)).start()

```

--------------------------------

### One screenshot per monitor

Source: https://python-mss.readthedocs.io/latest/examples.html

Iterates over each monitor and saves a screenshot for each, printing the generated filenames. Requires an active mss instance (sct).

```python
for filename in sct.save():
    print(filename)

```

--------------------------------

### MSS.shot()

Source: https://python-mss.readthedocs.io/latest/usage.html

Takes a screenshot and optionally saves it to a file or returns the raw data.

```APIDOC
## `MSS.shot()`

### Description
Takes a screenshot of the specified monitor and optionally saves it to a file.

### Method
`shot(monitor, output)`

### Parameters
- **monitor** (dict or `Monitor`) - Required - The monitor to capture.
- **output** (str or file-like object) - Required - The output file path or file object where the screenshot will be saved, or `None` to return the raw data.

### Returns
- The output file path if output is provided, otherwise the raw BGRA pixel data.

```

--------------------------------

### Screen capture with OpenCV using mss.ScreenShot.to_numpy(channels="BGR")

Source: https://python-mss.readthedocs.io/latest/examples.html

Captures a screen region and displays it in an OpenCV window, using `mss.ScreenShot.to_numpy()` with `channels="BGR"` for OpenCV compatibility. Press 'q' to quit. Added in version 3.0.0.

```python
import time

import cv2

import mss
from mss.models import Region

with mss.MSS() as sct:
    # Part of the screen to capture
    region = Region(left=0, top=40, width=800, height=640)

    while "Screen capturing":
        last_time = time.time()

        # Get raw pixels from the screen, save it to a NumPy array.
        # Note that OpenCV expects colors in BGR order.
        img = sct.grab(region).to_numpy(channels="BGR")

        # Display the picture
        cv2.imshow("OpenCV/NumPy normal", img)

        # Display the picture in grayscale
        # cv2.imshow('OpenCV/Numpy grayscale',
        #            cv2.cvtColor(img, cv2.COLOR_BGR2GRAY))

        print(f"fps: {1 / (time.time() - last_time)}")

        # Press "q" to quit
        if cv2.waitKey(25) & 0xFF == ord("q"):
            cv2.destroyAllWindows()
            break

```

--------------------------------

### MSS.monitors

Source: https://python-mss.readthedocs.io/latest/index.html

Returns a list of all available monitors.

```APIDOC
## MSS.monitors

### Description
Returns a list of all available monitors.

### Property
`monitors` (list) - List of Monitor objects.
```

--------------------------------

### MSS.shot()

Source: https://python-mss.readthedocs.io/latest/index.html

Captures a screenshot and returns the file name.

```APIDOC
## MSS.shot()

### Description
Captures a screenshot and returns the file name.

### Method
`shot(monitor=0, output='monitor-%d.png')`

### Parameters
- **monitor** (int or dict) - The monitor to capture (default 0).
- **output** (str) - The output file path template (default 'monitor-%d.png').

### Returns
- **str** - The output file name.
```

--------------------------------

### Clone MSS repository from GitHub

Source: https://python-mss.readthedocs.io/latest/installation.html

Clone the python-mss repository from GitHub and change into the directory.

```bash
$ git clone https://github.com/BoboTiG/python-mss.git
$ cd python-mss

```

--------------------------------

### Bad usage: creating MSS inside loop

Source: https://python-mss.readthedocs.io/latest/usage.html

Creates a new MSS instance on every iteration, which is inefficient. Avoid this pattern for repeated captures.

```python
for _ in range(100):
    with MSS() as sct:
        sct.shot()

```

--------------------------------

### GNU/Linux XShm backend

Source: https://python-mss.readthedocs.io/latest/examples.html

Explicitly select the XShmGetImage backend and inspect whether it is active or falling back to XGetImage. Added in version 10.2.0.

```python
from mss import MSS

with MSS(backend="xshmgetimage") as sct:
    screenshot = sct.grab(sct.monitors[1])
    print(f"Captured screenshot dimensions: {screenshot.size.width}x{screenshot.size.height}")

    print("Did MIT-SHM work:")
    for message in sct.performance_status:
        print(message)
```

--------------------------------

### Monitor.height

Source: https://python-mss.readthedocs.io/latest/support.html

Returns the height of the monitor.

```APIDOC
## `Monitor.height`

### Description
Returns the height of the monitor.
```

--------------------------------

### ScreenShot.raw

Source: https://python-mss.readthedocs.io/latest/index.html

Returns the raw pixel data.

```APIDOC
## ScreenShot.raw

### Description
Returns the raw pixel data.

### Property
`raw` (bytes) - The raw pixel data.
```

--------------------------------

### Grab screenshot using region dictionary

Source: https://python-mss.readthedocs.io/latest/usage.html

Pass a dictionary with top, left, width, and height to grab a specific region. Region dictionaries are supported for compatibility.

```python
screenshot = sct.grab({"top": 0, "left": 0, "width": 100, "height": 100})

```

--------------------------------

### Size.height

Source: https://python-mss.readthedocs.io/latest/support.html

Returns the height.

```APIDOC
## `Size.height`

### Description
Returns the height.
```

--------------------------------

### MSS.save()

Source: https://python-mss.readthedocs.io/latest/index.html

Saves a screenshot to a file.

```APIDOC
## MSS.save()

### Description
Saves a screenshot to a file.

### Method
`save(monitor=0, output='monitor-%d.png')`

### Parameters
- **monitor** (int or dict) - The monitor to capture (default 0).
- **output** (str) - The output file path template (default 'monitor-%d.png').
```

--------------------------------

### ScreenShot.rgb

Source: https://python-mss.readthedocs.io/latest/index.html

Returns the RGB pixel data.

```APIDOC
## ScreenShot.rgb

### Description
Returns the RGB pixel data.

### Property
`rgb` (bytes) - The RGB pixel data.
```

--------------------------------

### mss.MSS.max_displays property

Source: https://python-mss.readthedocs.io/latest/api.html

Maximum number of displays to handle. Availability: macOS.

```APIDOC
## max_displays property

### Description
Maximum number of displays to handle.

### Returns
int - Maximum number of displays.

### Notes
Availability: macOS. Added in version 8.0.0.
```

--------------------------------

### Import `Monitor` type from `mss.models`

Source: https://python-mss.readthedocs.io/latest/release-history/v10.2.0.html

Shows the import statement for the new `Monitor` type, which will replace monitor dictionaries in 11.0. This import works in both 10.2.x and 11.x.

```python
from mss.models import Monitor

```

--------------------------------

### Size.width

Source: https://python-mss.readthedocs.io/latest/support.html

Returns the width.

```APIDOC
## `Size.width`

### Description
Returns the width.
```
Tokens:
Raw