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.
// shell: node --expose-gc --max-semi-space-size=64 app.js
Try it
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.
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
// shell
node --v8-options
node --<v8-flag>[=<value>] <script>
// 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 compareheapUsed. NODE_OPTIONSallows only a safe subset of V8 flags (for example--max-old-space-sizeand--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-syntaxlets 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-sizesets the old generation limit, andv8.getHeapStatistics()reports the results. - Child processes receive V8 flags through
NODE_OPTIONS(if allowed) or explicitexecArgv.