Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท CLI Flags

Node.js --v8-options and --expose-gc flags

Reference for passing V8 flags to Node.js: list them with --v8-options, expose gc() with --expose-gc, set flags at runtime, and why most are for experts only.

Node.js embeds the V8 JavaScript engine, and V8 has hundreds of its own command-line options. Node accepts them directly on its command line: node --max-old-space-size=4096 app.js is a V8 flag, not a Node flag. node --v8-options prints every flag your build knows, with its type and default.

The best-known V8 flag for developers is --expose-gc, which adds a global gc() function so you can trigger a garbage collection by hand in tests and measurements. Most other V8 flags are for tuning and debugging the engine itself.

NODE
// shell: node --expose-gc --max-semi-space-size=64 app.js

Try it

Node.js gc() exists only with --expose-gc

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 Listing options and a flag set at runtime

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
// shell
node --v8-options
node --<v8-flag>[=<value>] <script>
NODE
// in code
v8.setFlagsFromString('--flag')
Name Description
--v8-options Prints all V8 flags, with descriptions, types and defaults, then exits.
--expose-gc Defines the global function gc().
--max-semi-space-size=<MB> Size of the young generation's semi-spaces. Raising it can speed up allocation-heavy programs.
--stack-size=<KB> Stack V8 may use (default about 984 KB). Setting it above the real operating-system stack size causes segmentation faults.
--trace-gc Prints a line for each garbage collection.

Returns: nothing. --v8-options ends the process after printing.

Errors: an unknown flag stops startup with bad option. Boolean flags can be negated (--no-flag); flags that take a value use --flag=value.

Usage notes

  • Flags are version-specific. A V8 flag can disappear or change meaning in any Node.js release, including minor ones. Do not bake them into long-lived deployment scripts without testing upgrades.
  • Use gc() for tests and measurements only. Normal programs should let V8 decide when to collect. Forcing collections slows the program and can hide real memory behavior.
  • Calling gc() in tests of memory: call it twice, or between measurements, so weak references and finalizers have a chance to run before you compare heapUsed.
  • NODE_OPTIONS allows only a safe subset of V8 flags (for example --max-old-space-size and --max-semi-space-size). Other flags must be on the command line.
  • v8.setFlagsFromString() after startup is risky. Changing a flag once the engine is running can have no effect or an undefined one; the V8 documentation warns about this. Prefer command-line flags.
  • --allow-natives-syntax lets code call internal %FunctionName() helpers and is for engine debugging only. It is a security risk if combined with untrusted code.
  • Related Node flags: --max-old-space-size sets the old generation limit, and v8.getHeapStatistics() reports the results.
  • Child processes receive V8 flags through NODE_OPTIONS (if allowed) or explicit execArgv.