Install & Compatibility
Where this runs
tested against v0.8.1 · 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.042s · 17.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.5s · import 0.038s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
get_monitors
✓ from screeninfo import get_monitors
get_primary_monitor
✓ from screeninfo import get_primary_monitor
Enumerator
✓ from screeninfo import get_monitors, Enumerator
Used to force a specific backend for monitor enumeration.
Monitor
✓ from screeninfo.common import Monitor
While 'Monitor' objects are returned by 'get_monitors', direct import is from screeninfo.common if needed for type hinting or inspection.
This quickstart code demonstrates how to retrieve information about all connected monitors and specifically the primary monitor using `screeninfo`.
from screeninfo import get_monitors, get_primary_monitor
print("Detected monitors:")
for m in get_monitors():
print(f" Monitor(x={m.x}, y={m.y}, width={m.width}, height={m.height}, is_primary={m.is_primary}, name={m.name})")
primary = get_primary_monitor()
if primary:
print(f"\nPrimary monitor: Monitor(x={primary.x}, y={primary.y}, width={primary.width}, height={primary.height}, name={primary.name})")
else:
print("\nNo primary monitor detected.")
Debug
Known issues
gotchaUsers, especially on macOS or certain Linux desktop environments (like Wayland), may encounter `screeninfo.common.ScreenInfoError: No enumerators available`. This indicates the library could not detect a compatible display backend.fixEnsure display drivers are correctly installed and that the environment is compatible with one of the supported backends (X11 for Linux, AppKit for macOS, etc.). Forcing a specific enumerator (e.g., `get_monitors(Enumerator.OSX)`) might sometimes help, but often points to a deeper environmental issue.
affects: All versions
gotchaThe maintainer explicitly states that they do not personally test on OSX or other environments, encouraging pull requests for these platforms. This may lead to slower support or platform-specific quirks being less promptly addressed.fixUsers on less-tested platforms should be aware of this and be prepared to contribute or work around platform-specific issues. Check GitHub issues for known platform-specific problems.
affects: All versions
gotchaSome users have reported `UnicodeDecodeError` during installation on certain Linux distributions (e.g., Arch Linux) when using poetry, potentially related to locale settings or poetry's deprecated `dev-dependencies` section.fixVerify that your system's locale settings are correctly configured for UTF-8. If using Poetry for development, be aware that `poetry.dev-dependencies` is deprecated; ensure your `pyproject.toml` uses `poetry.group.dev.dependencies` if you are developing `screeninfo` or a project that uses it with `poetry`.
affects: 0.8.1 and possibly earlier (installation process specific)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'screeninfo'
The 'screeninfo' package is not installed in the current Python environment.
fixpip install screeninfo
Xlib.error.DisplayError: Can't open display:
On Linux, screeninfo requires access to an X server. This error occurs when no X display is found or accessible, such as in a headless environment, SSH without X forwarding, or a misconfigured DISPLAY variable.
fixEnsure the script is run in a graphical environment or that the DISPLAY environment variable is correctly set. For headless servers, Xvfb can sometimes be used to provide a virtual display.
ModuleNotFoundError: No module named 'objc._objc'
On macOS, screeninfo relies on the pyobjc-core package, which might be missing or corrupted, preventing screeninfo from interacting with the macOS display APIs.
fixpip install pyobjc-core
AttributeError: module 'screeninfo' has no attribute 'primary_monitor'
This error occurs when trying to access 'primary_monitor' directly from the screeninfo module, which was part of an older API. The current version uses 'get_monitors()' and the 'is_primary' attribute on Monitor objects.
fixUse 'screeninfo.get_monitors()' and iterate through the list to find the primary monitor by checking the 'is_primary' attribute, for example: `primary_monitor = next((m for m in screeninfo.get_monitors() if m.is_primary), None)`
Upgrade
Version history
0.8.1latest on PyPI · released Sep 9, 2022
Audit
Dependencies
No dependency data recorded yet.