Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท util, assert and the Test Runner

Node.js util.inspect() function

Reference for util.inspect() in Node.js: depth, colors, compact, breakLength, sorted, showHidden and maxArrayLength options, with examples and pitfalls.

util.inspect(value, options) returns a string that shows a value the way console.log() prints it. It understands nested objects, arrays, Map and Set, classes, symbols, getters, circular references, typed arrays and more, and it can be tuned with a handful of options.

console.log() itself uses util.inspect() (through util.format()), so every option here also explains why logged output looks the way it does. Call inspect() directly when you need the text as a string, with different settings from the console's defaults.

NODE
import { inspect } from "node:util";

const text = inspect({ a: 1, b: { c: { d: { e: 1 } } } }, { depth: null });

Try it

Node.js depth, compact and sorted

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 Limits, circular references and colors

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
util.inspect(object: any, options?: InspectOptions): string
util.inspect(object: any, showHidden?: boolean, depth?: number | null, colors?: boolean): string
Option Description
showHidden Also show non-enumerable properties and symbols (default false).
depth How many levels of nesting to expand (default 2); null or Infinity means unlimited. Deeper objects print as [Object] or [Array].
colors Add ANSI color escape codes (default false).
customInspect Honor [util.inspect.custom] methods (default true).
showProxy Show the target and handler of a Proxy instead of just the target view (default false).
maxArrayLength Maximum number of array, Set, Map and typed-array elements shown (default 100); null for all.
maxStringLength Maximum characters of a string shown (default 10000); null for all.
breakLength Line width at which output wraps (default 80; Infinity keeps it on one line).
compact true/false, or a number (default 3): how many inner levels may be merged on one line when they fit. false puts every property on its own line.
sorted true or a comparison function to sort object keys.
getters true, "get" or "set" to evaluate and show getters and setters (default false).
numericSeparator Show numbers like 1_000_000 (default false).

Returns: a string. It is never undefined, even for undefined input ('undefined').

Errors / edge cases: invalid option types throw ERR_INVALID_ARG_TYPE. Circular references print as <ref *1> and [Circular *1]. With getters: true, a getter is run, so one with side effects or one that throws is evaluated during formatting.

Usage notes

  • The default depth of 2 hides data. If a log line shows [Object], raise depth or pass null. console.dir(obj, { depth: null }) is the shortcut.
  • Output is for humans, not machines. The format is not stable between Node versions and cannot be parsed back. Use JSON.stringify() for data exchange.
  • colors: true adds escape codes to the string; strip them with util.stripVTControlCharacters() if you store the text.
  • Strings are quoted and escaped inside objects but not at the top level of console.log(). inspect("a") returns 'a' with the quotes.
  • Classes print by name (Point { x: 3, y: 4 }); only own properties are listed, so getters defined in a class body (on the prototype) never appear; objects without a prototype print as [Object: null prototype].
  • Customize your own classes with the util.inspect.custom symbol; see util.inspect.custom.
  • Global defaults can be changed through util.inspect.defaultOptions, which affects every console.log() call in the process. Prefer per-call options in libraries.
  • Large structures are slow to format. Keep maxArrayLength and depth small when logging in hot paths.