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.
// shell: NODE_OPTIONS="--max-old-space-size=2048 --enable-source-maps" node 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 (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-sizefor the heap limit,--enable-source-maps,--requireor--importto 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
envtochild_processto avoid surprises, or filter the variable out. --inspectis 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 commandform works in POSIX shells only. On Windows usesetin cmd,$env:in PowerShell, or a helper such ascross-env. Node's own--env-filecan also set it: putNODE_OPTIONS=...in the file and Node reads it at startup. - Visibility.
process.env.NODE_OPTIONSshows the raw string;process.execArgvdoes 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.