Your company here ā€” click to reach over 10,000 unique daily visitors

darkman - Man Page

daemon for dark-mode and light-mode transitions on Unix-like desktops


darkman run
darkman set [light|dark]
darkman get
darkman toggle


darkman runs in the background and turns on dark mode at sundown, and turns it off again at sunrise. darkman is not designed to be used interactively: it's designed to be set up once, and run in the background.

It is, however, possible to trigger manual transitions and even disable automatic transitions entirely.



Runs the darkman service. This command is intended to be executed by a service manager, init script or alike.

set <light|dark>

Sets the current mode.


Prints the current mode.


Toggle the current mode.


The open source desktop ecosystem is quite heterogeneous and switching between dark/light mode on different applications requires different mechanism and techniques.

Darkman seeks to implement the more widely supported standards, while leaving room for users to hook in custom scripts for other applications.

Darkman implements the FreeDesktop dark mode standard. Applications using this API should switch to dark/light mode based on darkman's current preference. This standard was originally pushed by the GNOME and Elementary teams, and is currently supported by KDE, Firefox and many other projects. You should expect applications from those environment to support it, amongst others.

For additional application support, custom executables (including simple shell scripts) can be placed in the following two directories:

Scripts need to have an executable bit set, or will not be executed.

For additional sample scripts (and discussion on how to integrate different applications) see the project website:

For custom integrations, darkman exposes a D-Bus API which allows querying and controlling the current mode. The get, set and toggle commands all use this API. Usage of this API is also the recommended approach when writing custom tools (e.g.: switching the current mode based on the input from a light sensor).

For Emacs users, a third party package exists to integrate darkman with Emacs:


darkman will automatically determine the system's location using geoclue. Geoclue's reliability varies depending on distribution and desktop environment, and it will often not work without a geoclue agent running.

If using geoclue is not an option, the location may be specified explicitly via a configuration file.


A configuration file and all settings are optional. Configuration is read from ~/.config/darkman/config.yaml, and has the following format:

  lat: 52.3
  lng: 4.8
  dbusserver: true

The following settings are available:


The following environment variables are also read and will override the configuration file:


Overrides the latitude for the current location.


Overrides the longitude for the current location.


Overrides whether to expose the current mode via D-Bus.


Darkman will trigger a darkmode/lightmode transition at sundown in the current location. When a web browser applies this transition at the same time, open websites can use this information to extrapolate some information about the current location.


For issues and general development inquiries, see the project home currently hosted at GitLab:

See Also



Developed by Hugo O. Barrera <hugo@whynothugo.nl>, with invaluable contributions from the community.

darkman is an open source project licensed under the ISC licence and developed for anyone to use freely. If you would like to sponsor this project, see: