Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท CLI Flags

Node.js NODE_OPTIONS environment variable

Reference for NODE_OPTIONS: set Node.js command-line flags through the environment, which flags are allowed, quoting rules and how it combines with real arguments.

NODE_OPTIONS is an environment variable that holds extra command-line flags for every node process that sees it. It is the way to change Node's behavior when you cannot edit the command that starts it: a test runner spawning workers, a framework CLI, a process manager, a container image, or a package.json script that calls a tool which in turn runs node.

The value is split on spaces into flags, in the same form you would type them. Because child processes inherit the environment, the flags also reach every Node process your program spawns, unless you replace the environment.

NODE
// shell: NODE_OPTIONS="--max-old-space-size=2048 --enable-source-maps" node app.js

Try it

Node.js Flags from the environment

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 Disallowed flags and a preload module

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 (POSIX):   NODE_OPTIONS="--flag1 --flag2=value" node app.js
// PowerShell:      $env:NODE_OPTIONS = "--flag1 --flag2=value"
// package.json:    "start": "NODE_OPTIONS=--enable-source-maps node app.js"
Part Description
Value Flags separated by spaces. Use --flag=value form; the --flag value form works for flags that take an argument, but = is clearer.
Quoting Wrap an argument that contains a space in double quotes inside the value, for example --require "/my dir/setup.js".
Precedence NODE_OPTIONS is applied first, then the real command-line flags, so the command line wins when both set the same flag.
Inheritance Child processes spawned with the default environment inherit it.

Errors: if the value contains a flag that is not allowed, Node prints ... is not allowed in NODE_OPTIONS and exits with code 9. Unknown flags produce a bad-option error in the same way.

Usage notes

  • Only a safe subset is allowed. Flags that run code from the command line or change how the process is invoked (-e, -p, --check, --interactive, --test, and similar) are refused, as are most V8 flags unless they appear on the allowed list. The authoritative list is in the CLI documentation for your release.
  • Typical uses: --max-old-space-size for the heap limit, --enable-source-maps, --require or --import to preload instrumentation, --conditions, --disable-warning, --stack-trace-limit, --inspect.
  • Child processes inherit it. A heap limit meant for your server also applies to workers and spawned tools. Pass an explicit env to child_process to avoid surprises, or filter the variable out.
  • --inspect is risky here. Every inherited Node process then tries to open the same debug port. Prefer launching the one process you want to debug.
  • Cross-platform setting. The VAR=value command form works in POSIX shells only. On Windows use set in cmd, $env: in PowerShell, or a helper such as cross-env. Node's own --env-file can also set it: put NODE_OPTIONS=... in the file and Node reads it at startup.
  • Visibility. process.env.NODE_OPTIONS shows the raw string; process.execArgv does not include these flags.
  • Security. Anyone who can set the environment of a Node process can preload code with --require. Treat the environment of production processes as trusted input only.