{"id":4346,"library":"darkdetect","title":"Darkdetect","description":"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.","status":"active","version":"0.8.0","language":"en","source_language":"en","source_url":"https://github.com/albertosottile/darkdetect","tags":["dark mode","OS theme","GUI","macOS","Windows","Linux","theme detection"],"install":[{"cmd":"pip install darkdetect","lang":"bash","label":"Basic Installation"},{"cmd":"pip install darkdetect[macos-listener]","lang":"bash","label":"macOS Listener Support (Optional)"}],"dependencies":[{"reason":"The core package is designed not to depend on modules or packages not already included in standard Python distributions.","package":"None (standard library)"},{"reason":"Required for the macOS listener functionality, installed via the `macos-listener` extra. Specific components are OS-dependent and are handled by the extra installation.","package":"Additional components","optional":true}],"imports":[{"symbol":"darkdetect","correct":"import darkdetect"}],"quickstart":{"code":"import darkdetect\nimport threading\nimport time\n\n# Check the current theme state\ncurrent_theme = darkdetect.theme()\nprint(f\"Current OS theme: {current_theme}\")\nprint(f\"Is Dark mode: {darkdetect.isDark()}\")\nprint(f\"Is Light mode: {darkdetect.isLight()}\")\n\n# Example of using the listener for theme changes\ndef theme_changed_callback(new_theme: str):\n    print(f\"[Listener] Theme changed to: {new_theme} at {time.time()}\")\n\nprint(\"\\nStarting a background listener (runs for 5 seconds)...\")\n# The darkdetect.Listener class offers more control over stopping.\n# For a simple runnable quickstart, darkdetect.listener (a wrapper) is shown in docs,\n# but for proper cleanup, using the Listener class explicitly is often better.\n# We'll use the Listener class to demonstrate a controllable listener.\n\nlistener_instance = darkdetect.Listener(theme_changed_callback)\nlistener_thread = threading.Thread(target=listener_instance.listen, daemon=True)\nlistener_thread.start()\n\n# Let the listener run for a few seconds to detect any immediate changes\ntime.sleep(5)\n\n# Stop the listener gracefully\nlistener_instance.stop(timeout=1)\nprint(\"Background listener stopped.\")","lang":"python","description":"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."},"warnings":[{"fix":"Always check for `None` return values before processing theme information, e.g., `if darkdetect.isDark() is True: ...`","message":"The `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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade to Python 3.6 or newer, or use `darkdetect<=0.7.x` for older Python environments.","message":"Python 2.7 and Python versions older than 3.6 are no longer supported from `darkdetect` version 0.8.0 onwards.","severity":"breaking","affected_versions":">=0.8.0"},{"fix":"Be aware that this specific macOS UI element's theme state is not reflected by `darkdetect`.","message":"On macOS, the detection of the dark menu bar and dock option (available from macOS 10.10) is specifically not supported by `darkdetect`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For bundled macOS applications, test the listener functionality thoroughly. Ensure proper process management when integrating the listener, especially on macOS.","message":"When 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.","severity":"gotcha","affected_versions":"All versions with macOS listener"},{"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.","message":"On 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.","severity":"gotcha","affected_versions":"All versions with Windows listener"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}