Registry / observability / darkdetect

darkdetect

JSON →
library0.8.0pypypi✓ verified 24d ago

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 darkdetect
INSTALL
IMPORT
SIG · DARKDETECT
D
darkdetect
observabilitypythonv0.8.0
Install
1.5s avg
Import
19ms
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.8.0 · 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
musl
py 3.103.910 runs
installs and imports cleanly · install 0.0s · import 0.020s · 17.8MB
glibc
py 3.103.910 runs
installs and imports cleanly · install 1.5s · import 0.018s · 18MB
16MB installed
● package 16MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

darkdetect
import darkdetect

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.

import darkdetect import threading import time # Check the current theme state current_theme = darkdetect.theme() print(f"Current OS theme: {current_theme}") print(f"Is Dark mode: {darkdetect.isDark()}") print(f"Is Light mode: {darkdetect.isLight()}") # Example of using the listener for theme changes def theme_changed_callback(new_theme: str): print(f"[Listener] Theme changed to: {new_theme} at {time.time()}") print("\nStarting a background listener (runs for 5 seconds)...") # The darkdetect.Listener class offers more control over stopping. # For a simple runnable quickstart, darkdetect.listener (a wrapper) is shown in docs, # but for proper cleanup, using the Listener class explicitly is often better. # We'll use the Listener class to demonstrate a controllable listener. listener_instance = darkdetect.Listener(theme_changed_callback) listener_thread = threading.Thread(target=listener_instance.listen, daemon=True) listener_thread.start() # Let the listener run for a few seconds to detect any immediate changes time.sleep(5) # Stop the listener gracefully listener_instance.stop(timeout=1) print("Background listener stopped.")
Debug
Known issues
gotchaThe `darkdetect.theme()`, `isDark()`, and `isLight()` functions will return `None` if the operating system is not supported (e.g., older macOS/Windows versions, or Linux without a detectable GTK dark theme) or if the theme cannot be determined for other reasons.
fix
Always check for `None` return values before processing theme information, e.g., `if darkdetect.isDark() is True: ...`
affects: All versions
breakingPython 2.7 and Python versions older than 3.6 are no longer supported from `darkdetect` version 0.8.0 onwards.
fix
Upgrade to Python 3.6 or newer, or use `darkdetect<=0.7.x` for older Python environments.
affects: >=0.8.0
gotchaOn macOS, the detection of the dark menu bar and dock option (available from macOS 10.10) is specifically not supported by `darkdetect`.
fix
Be aware that this specific macOS UI element's theme state is not reflected by `darkdetect`.
affects: All versions
gotchaWhen using the listener API on macOS in a bundled application where `sys.executable` is not a Python interpreter, the listener might not function correctly. Additionally, the macOS listener may leave unkilled processes when the application terminates.
fix
For bundled macOS applications, test the listener functionality thoroughly. Ensure proper process management when integrating the listener, especially on macOS.
affects: All versions with macOS listener
gotchaOn Windows, calling `Listener.stop(None)` (to stop with no timeout) might not immediately terminate the underlying listener process until another theme change is detected. While no further callbacks will be made, the process might persist.
fix
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.
affects: All versions with Windows listener
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'darkdetect'
The `darkdetect` package is not installed in the Python environment currently in use, or there is a conflict due to multiple Python installations (e.g., when using Anaconda or different virtual environments).
fix
Ensure `darkdetect` is installed in the correct Python environment using pip: `pip install darkdetect`.
darkdetect.theme() returns None
The `darkdetect` library is being executed on an operating system or OS version that it does not support for dark mode detection, or on Linux without a properly configured dark GTK theme. Supported versions are macOS 10.14+, Windows 10 1607+, and Linux with a dark GTK theme.
fix
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.
darkdetect listener not working
The macOS listener API in `darkdetect` may not function correctly within bundled applications (e.g., those created with PyInstaller) because it relies on `sys.executable` being a Python interpreter that supports the `-c` argument, which is often not the case for compiled binaries.
fix
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.
Upgrade
Version history
0.8.0latest on PyPI · released Dec 16, 2022
Audit
Dependencies
None (standard library)requiredThe core package is designed not to depend on modules or packages not already included in standard Python distributions.
Additional componentsoptionalRequired for the macOS listener functionality, installed via the `macos-listener` extra. Specific components are OS-dependent and are handled by the extra installation.
Agent activity
22 hits · last 30 days
node
20
OpenAI (training)
1
Resources