Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท CLI Flags

Node.js NO_COLOR and FORCE_COLOR environment variables

Reference for NO_COLOR and FORCE_COLOR in Node.js: how they affect util.styleText(), console and the test runner, and how to read the color depth of a stream.

Terminals understand escape sequences that change text color, but files, CI logs and pipes show those sequences as noise. Node.js therefore colors its own output (error stack highlights, util.inspect() with colors, the test runner, util.styleText()) only when it thinks the destination can display them, and it lets the environment override that guess.

Two variables are honored. NO_COLOR (any non-empty value) asks programs to stay plain. FORCE_COLOR forces colors on, even when output is piped. Their values follow common conventions shared with many other tools, so one setting works across your toolchain.

NODE
// shell: NO_COLOR=1 node app.js        FORCE_COLOR=1 node app.js | less -R

Try it

Node.js What util.styleText() does

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Reading the color depth

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
// NO_COLOR=<any non-empty value>
// FORCE_COLOR=<0 | 1 | 2 | 3 | true | false | empty>
// stream.getColorDepth([env]): 1 | 4 | 8 | 24      (tty.WriteStream)
// stream.hasColors([count][, env]): boolean         (tty.WriteStream)
// util.styleText(format, text[, { validateStream, stream }]): string
FORCE_COLOR value Effect
0 or false Colors off.
empty, 1 or true 16 colors.
2 256 colors.
3 True color (16 million).

Returns: getColorDepth() returns the number of color bits (1, 4, 8 or 24); styleText() returns the text wrapped in escape codes, or the plain text when colors are not wanted.

Usage notes

  • Precedence. If both are set, FORCE_COLOR wins and Node prints a warning that NO_COLOR is ignored. Do not set both.
  • Pipes and files are plain by default. Only a real terminal (process.stdout.isTTY) gets colors on its own. FORCE_COLOR is the way to keep colors in CI logs viewers that render them.
  • util.styleText() checks the stream (stdout by default) and drops the codes when it is not a color-capable terminal. Pass { validateStream: false } to always get the codes, or { stream: process.stderr } to check another stream.
  • Child processes inherit the variables, so setting FORCE_COLOR=1 in a parent also colors spawned Node tools. Test runners and CLIs built on Node usually honor them too.
  • getColorDepth() only exists on TTY streams. For a pipe, process.stdout.getColorDepth is undefined; the example above calls the prototype method to show what the environment alone would give.
  • Other hints it reads: TERM (for example dumb means none) and COLORTERM=truecolor. NODE_DISABLE_COLORS is an older way to switch colors off.
  • Library code should not hard-code escape sequences. Use styleText() or check hasColors() so users with NO_COLOR set are respected.
  • Windows: modern terminals understand the same sequences; legacy consoles may not, and Node reports a low color depth there.