#terminal #background-color #light #dark #terminal-colors #color

bin+lib terminal-light

tells you whether your terminal is dark or light

17 releases (7 stable)

1.4.0 Mar 11, 2024
1.2.0 Jan 15, 2024
1.1.1 Feb 19, 2023
1.0.1 Sep 26, 2022
0.6.1 Nov 11, 2021

#89 in Command-line interface

Download history 955/week @ 2024-01-21 915/week @ 2024-01-28 1348/week @ 2024-02-04 1130/week @ 2024-02-11 955/week @ 2024-02-18 1048/week @ 2024-02-25 1152/week @ 2024-03-03 1939/week @ 2024-03-10 1090/week @ 2024-03-17 999/week @ 2024-03-24 1106/week @ 2024-03-31 951/week @ 2024-04-07 844/week @ 2024-04-14 842/week @ 2024-04-21 1039/week @ 2024-04-28 842/week @ 2024-05-05

3,650 downloads per month
Used in 15 crates (8 directly)

MIT license

100 lines

MIT Latest Version docs Chat on Miaou


This crate answers the question "Is the terminal dark or light?".

It provides

  • the background color, either as RGB or ANSI
  • the background color's luma, which varies from 0 (black) to 1 (white)

A use case in a TUI is to determine what set of colors would be most suitable depending on the terminal's background:

let should_use_light_skin = terminal_light::luma()
    .map_or(false, |luma| luma > 0.6);

If you have very specialized skins, you may choose a more precise switch:

match terminal_light::luma() {
    Ok(luma) if luma > 0.85 => {
        // Use a "light mode" skin.
    Ok(luma) if luma < 0.2 => {
        // Use a "dark mode" skin.
    _ => {
        // Either we couldn't determine the mode or it's kind of medium.
        // We should use an itermediate skin, or one defining the background.

See the included example:




Here are the various strategies automatically used by terminal-light to answer the big question:

$COLORFGBG strategy

This environment variable is set by some terminals, like konsole or the rxvt family. It can also be set by users. Its value is like 15;0 where the second number is the ANSI code for the background color.


  • querying an env variable is a fast operation


  • this env variable isn't always immediately updated when you change the color of the terminal
  • the value isn't precise: 0 is "dark" and 15 is "light" but the real RGB color is uncertain as the low ANSI codes are often modified by the user

"Dynamic colors" OSC escape sequence strategy

Modern terminals implement this xterm extension: a query making it possible to know the background color as RGB.

Terminal-light sends the query on stdout, waits for the answer on stdin with a timeout of 20ms, then parses this answer.


  • this works well on all tested unix terminals, including on MacOs
  • the value is precise (RGB)
  • the value is up to date when it's available


  • waiting for stdin with a timeout isn't implemented on Windows in this crate (help welcome)
  • this isn't instant, a delay of 10 ms to get the answer isn't unusual
  • if a not compatible terminal doesn't answer at all, we're waiting for 20ms
  • it may fail on some terminal multiplexers

Global strategy used by Terminal-light

  1. if we're on a unix-like platform, we try the escape sequence strategy
  2. if it failed or we're not on unix, we try the $COLORFGBG strategy
  3. without a solution, we return a TlError::Unsupported error


~73K SLoC