Darkdetect

Warnings

• gotcha 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.
  Fix: Always check for `None` return values before processing theme information, e.g., `if darkdetect.isDark() is True: ...`
• breaking Python 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.
• gotcha On 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`.
• gotcha 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.
  Fix: For bundled macOS applications, test the listener functionality thoroughly. Ensure proper process management when integrating the listener, especially on macOS.
• gotcha 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.
  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.

Install

• pip install darkdetect Basic Installation
• pip install darkdetect[macos-listener] macOS Listener Support (Optional)

Imports

• darkdetect

  import darkdetect

Quickstart

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.")