Darkdetect is a Python library designed to detect if the operating system is currently in Dark Mode. It supports macOS (10.14+), Windows (10 1607+), and Linux (with a dark GTK theme). This package is particularly useful for Python GUI applications (Tkinter, wx, PyQt, PySide, etc.) that need to adapt their interface based on the system's theme settings. The current version is 0.8.0, and its release cadence has been infrequent, with the last major update in December 2022.
pip install darkdetectVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to immediately detect the OS dark mode and how to set up a listener to react to theme changes. The `darkdetect.theme()`, `darkdetect.isDark()`, and `darkdetect.isLight()` functions provide immediate status. The `darkdetect.Listener` class can be run in a separate thread to asynchronously detect and report theme changes via a callback function.
Always check for `None` return values before processing theme information, e.g., `if darkdetect.isDark() is True: ...`
Upgrade to Python 3.6 or newer, or use `darkdetect<=0.7.x` for older Python environments.
Be aware that this specific macOS UI element's theme state is not reflected by `darkdetect`.
For bundled macOS applications, test the listener functionality thoroughly. Ensure proper process management when integrating the listener, especially on macOS.
Consider using `Listener.stop(timeout=...)` with a reasonable timeout, or be aware that the listener process might linger until the next theme change or application exit.
Ensure `darkdetect` is installed in the correct Python environment using pip: `pip install darkdetect`.
Verify that the operating system and its version meet the requirements for `darkdetect`. If running on an unsupported system, handle the `None` return value gracefully in your code by providing a fallback or default theme.
For bundled applications, consider avoiding the `darkdetect` listener and instead periodically check the theme using `darkdetect.theme()` or `darkdetect.isDark()`. For macOS with PyInstaller, a known workaround for the `darkdetect-angr` fork involves a specific prefix to the command, but for the main `darkdetect` library, direct listener support in bundled apps is a known limitation.