Synopsis#

node [options] [V8 options] [<program-entry-point> | -e "script" | -] [--] [arguments]

node inspect [<program-entry-point> | -e "script" | <host>:<port>] …

node --v8-options

Execute without arguments to start theREPL.

For more info aboutnode inspect, see thedebugger documentation.

Program entry point#

The program entry point is a specifier-like string. If the string is not anabsolute path, it's resolved as a relative path from the current workingdirectory. That path is then resolved byCommonJS module loader, or by theES module loader if--experimental-default-type=moduleis passed. If no corresponding file is found, an error is thrown.

If a file is found, its path will be passed to theES module loader under any of the following conditions:

• The program was started with a command-line flag that forces the entrypoint to be loaded with ECMAScript module loader, such as--import or--experimental-default-type=module.
• The file has an.mjs extension.
• The file does not have a.cjs extension, and the nearest parentpackage.json file contains a top-level"type" field with a value of"module".

Otherwise, the file is loaded using the CommonJS module loader. SeeModules loaders for more details.

ECMAScript modules loader entry point caveat#

When loading, theES module loader loads the programentry point, thenode command will accept as input only files with.js,.mjs, or.cjs extensions; with.wasm extensions when--experimental-wasm-modules is enabled; and with no extension when--experimental-default-type=module is passed.

Options#

All options, including V8 options, allow words to be separated by bothdashes (-) or underscores (_). For example,--pending-deprecation isequivalent to--pending_deprecation.

If an option that takes a single value (such as--max-http-header-size) ispassed more than once, then the last passed value is used. Options from thecommand line take precedence over options passed through theNODE_OPTIONSenvironment variable.

-#

Alias for stdin. Analogous to the use of- in other command-line utilities,meaning that the script is read from stdin, and the rest of the optionsare passed to that script.

--#

Indicate the end of node options. Pass the rest of the arguments to the script.If no script filename or eval/print script is supplied prior to this, thenthe next argument is used as a script filename.

--abort-on-uncaught-exception#

Aborting instead of exiting causes a core file to be generated for post-mortemanalysis using a debugger (such aslldb,gdb, andmdb).

If this flag is passed, the behavior can still be set to not abort throughprocess.setUncaughtExceptionCaptureCallback() (and through usage of thenode:domain module that uses it).

--build-snapshot#

Generates a snapshot blob when the process exits and writes it todisk, which can be loaded later with--snapshot-blob.

When building the snapshot, if--snapshot-blob is not specified,the generated blob will be written, by default, tosnapshot.blobin the current working directory. Otherwise it will be written tothe path specified by--snapshot-blob.

$echo"globalThis.foo = 'I am from the snapshot'" > snapshot.js#Run snapshot.js to initialize the application and snapshot the#state of it into snapshot.blob.$node --snapshot-blob snapshot.blob --build-snapshot snapshot.js$echo"console.log(globalThis.foo)" > index.js#Load the generated snapshot and start the application from index.js.$node --snapshot-blob snapshot.blob index.jsI am from the snapshotcopy

Thev8.startupSnapshot API can be used to specify an entry point atsnapshot building time, thus avoiding the need of an additional entryscript at deserialization time:

$echo"require('v8').startupSnapshot.setDeserializeMainFunction(() => console.log('I am from the snapshot'))" > snapshot.js$node --snapshot-blob snapshot.blob --build-snapshot snapshot.js$node --snapshot-blob snapshot.blobI am from the snapshotcopy

For more information, check out thev8.startupSnapshot API documentation.

Currently the support for run-time snapshot is experimental in that:

1. User-land modules are not yet supported in the snapshot, so onlyone single file can be snapshotted. Users can bundle their applicationsinto a single script with their bundler of choice before buildinga snapshot, however.
2. Only a subset of the built-in modules work in the snapshot, though theNode.js core test suite checks that a few fairly complex applicationscan be snapshotted. Support for more modules are being added. If anycrashes or buggy behaviors occur when building a snapshot, please filea report in theNode.js issue tracker and link to it in thetracking issue for user-land snapshots.

--completion-bash#

Print source-able bash completion script for Node.js.

$node --completion-bash > node_bash_completion$source node_bash_completioncopy

-C condition,--conditions=condition#

Enable experimental support for customconditional exports resolutionconditions.

Any number of custom string condition names are permitted.

The default Node.js conditions of"node","default","import", and"require" will always apply as defined.

For example, to run a module with "development" resolutions:

$node -C development app.jscopy

--cpu-prof#

Starts the V8 CPU profiler on start up, and writes the CPU profile to diskbefore exit.

If--cpu-prof-dir is not specified, the generated profile is placedin the current working directory.

If--cpu-prof-name is not specified, the generated profile isnamedCPU.${yyyymmdd}.${hhmmss}.${pid}.${tid}.${seq}.cpuprofile.

$node --cpu-prof index.js$ls *.cpuprofileCPU.20190409.202950.15293.0.0.cpuprofilecopy

--cpu-prof-dir#

Specify the directory where the CPU profiles generated by--cpu-prof willbe placed.

The default value is controlled by the--diagnostic-dir command-line option.

--cpu-prof-interval#

Specify the sampling interval in microseconds for the CPU profiles generatedby--cpu-prof. The default is 1000 microseconds.

--cpu-prof-name#

Specify the file name of the CPU profile generated by--cpu-prof.

--diagnostic-dir=directory#

Set the directory to which all diagnostic output files are written.Defaults to current working directory.

Affects the default output directory of:

• --cpu-prof-dir
• --heap-prof-dir
• --redirect-warnings

--disable-proto=mode#

Disable theObject.prototype.__proto__ property. Ifmode isdelete, theproperty is removed entirely. Ifmode isthrow, accesses to theproperty throw an exception with the codeERR_PROTO_ACCESS.

--disallow-code-generation-from-strings#

Make built-in language features likeeval andnew Function that generatecode from strings throw an exception instead. This does not affect the Node.jsnode:vm module.

--dns-result-order=order#

Set the default value ofverbatim indns.lookup() anddnsPromises.lookup(). The value could be:

• ipv4first: sets defaultverbatimfalse.
• verbatim: sets defaultverbatimtrue.

The default isverbatim anddns.setDefaultResultOrder() have higherpriority than--dns-result-order.

--enable-fips#

Enable FIPS-compliant crypto at startup. (Requires Node.js to be builtagainst FIPS-compatible OpenSSL.)

--enable-network-family-autoselection#

Enables the family autoselection algorithm unless connection options explicitlydisables it.

--enable-source-maps#

EnableSource Map v3 support for stack traces.

When using a transpiler, such as TypeScript, stack traces thrown by anapplication reference the transpiled code, not the original source position.--enable-source-maps enables caching of Source Maps and makes a besteffort to report stack traces relative to the original source file.

OverridingError.prepareStackTrace prevents--enable-source-maps frommodifying the stack trace.

Note, enabling source maps can introduce latency to your applicationwhenError.stack is accessed. If you accessError.stack frequentlyin your application, take into account the performance implicationsof--enable-source-maps.

--experimental-global-customevent#

Expose theCustomEvent Web API on the global scope.

--experimental-global-webcrypto#

Expose theWeb Crypto API on the global scope.

--experimental-default-type=type#

Define which module system,module orcommonjs, to use for the following:

• String input provided via--eval or STDIN, if--input-type is unspecified.

• Files ending in.js or with no extension, if there is nopackage.json filepresent in the same folder or any parent folder.

• Files ending in.js or with no extension, if the nearest parentpackage.json field lacks a"type" field; unless thepackage.json folderor any parent folder is inside anode_modules folder.

In other words,--experimental-default-type=module flips all the places whereNode.js currently defaults to CommonJS to instead default to ECMAScript modules,with the exception of folders and subfolders belownode_modules, for backwardcompatibility.

Under--experimental-default-type=module and--experimental-wasm-modules,files with no extension will be treated as WebAssembly if they begin with theWebAssembly magic number (\0asm); otherwise they will be treated as ES moduleJavaScript.

--experimental-import-meta-resolve#

Enable experimentalimport.meta.resolve() parent URL support, which allowspassing a secondparentURL argument for contextual resolution.

Previously gated the entireimport.meta.resolve feature.

--experimental-loader=module#

This flag is discouraged and may be removed in a future version of Node.js.Please use--import withregister() instead.

Specify themodule containing exportedmodule customization hooks.module may be any string accepted as animport specifier.

--experimental-network-imports#

Enable experimental support for thehttps: protocol inimport specifiers.

--experimental-policy#

Use the specified file as a security policy.

--no-experimental-fetch#

Disable experimental support for theFetch API.

--no-experimental-repl-await#

Use this flag to disable top-level await in REPL.

--experimental-shadow-realm#

Use this flag to enableShadowRealm support.

--experimental-specifier-resolution=mode#

Sets the resolution algorithm for resolving ES module specifiers. Valid optionsareexplicit andnode.

The default isexplicit, which requires providing the full path to amodule. Thenode mode enables support for optional file extensions andthe ability to import a directory that has an index file.

Seecustomizing ESM specifier resolution for example usage.

--experimental-test-coverage#

When used in conjunction with thenode:test module, a code coverage report isgenerated as part of the test runner output. If no tests are run, a coveragereport is not generated. See the documentation oncollecting code coverage from tests for more details.

--experimental-vm-modules#

Enable experimental ES Module support in thenode:vm module.

--experimental-wasi-unstable-preview1#

Enable experimental WebAssembly System Interface (WASI) support.

--experimental-wasm-modules#

Enable experimental WebAssembly module support.

--force-context-aware#

Disable loading native addons that are notcontext-aware.

--force-fips#

Force FIPS-compliant crypto on startup. (Cannot be disabled from script code.)(Same requirements as--enable-fips.)

--frozen-intrinsics#

Enable experimental frozen intrinsics likeArray andObject.

Only the root context is supported. There is no guarantee thatglobalThis.Array is indeed the default intrinsic reference. Code may breakunder this flag.

To allow polyfills to be added,--require and--import both run before freezing intrinsics.

--force-node-api-uncaught-exceptions-policy#

EnforcesuncaughtException event on Node-API asynchronous callbacks.

To prevent from an existing add-on from crashing the process, this flag is notenabled by default. In the future, this flag will be enabled by default toenforce the correct behavior.

--heapsnapshot-near-heap-limit=max_count#

Writes a V8 heap snapshot to disk when the V8 heap usage is approaching theheap limit.count should be a non-negative integer (in which caseNode.js will write no more thanmax_count snapshots to disk).

When generating snapshots, garbage collection may be triggered and bringthe heap usage down. Therefore multiple snapshots may be written to diskbefore the Node.js instance finally runs out of memory. These heap snapshotscan be compared to determine what objects are being allocated during thetime consecutive snapshots are taken. It's not guaranteed that Node.js willwrite exactlymax_count snapshots to disk, but it will tryits best to generate at least one and up tomax_count snapshots before theNode.js instance runs out of memory whenmax_count is greater than0.

Generating V8 snapshots takes time and memory (both memory managed by theV8 heap and native memory outside the V8 heap). The bigger the heap is,the more resources it needs. Node.js will adjust the V8 heap to accommodatethe additional V8 heap memory overhead, and try its best to avoid using upall the memory available to the process. When the process usesmore memory than the system deems appropriate, the process may be terminatedabruptly by the system, depending on the system configuration.

$node --max-old-space-size=100 --heapsnapshot-near-heap-limit=3 index.jsWrote snapshot to Heap.20200430.100036.49580.0.001.heapsnapshotWrote snapshot to Heap.20200430.100037.49580.0.002.heapsnapshotWrote snapshot to Heap.20200430.100038.49580.0.003.heapsnapshot<--- Last few GCs --->[49580:0x110000000]     4826 ms: Mark-sweep 130.6 (147.8) -> 130.5 (147.8) MB, 27.4 / 0.0 ms  (average mu = 0.126, current mu = 0.034) allocation failure scavenge might not succeed[49580:0x110000000]     4845 ms: Mark-sweep 130.6 (147.8) -> 130.6 (147.8) MB, 18.8 / 0.0 ms  (average mu = 0.088, current mu = 0.031) allocation failure scavenge might not succeed<--- JS stacktrace --->FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory....copy

--heapsnapshot-signal=signal#

Enables a signal handler that causes the Node.js process to write a heap dumpwhen the specified signal is received.signal must be a valid signal name.Disabled by default.

$node --heapsnapshot-signal=SIGUSR2 index.js &$ps auxUSER       PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMANDnode         1  5.5  6.1 787252 247004 ?       Ssl  16:43   0:02 node --heapsnapshot-signal=SIGUSR2 index.js$kill -USR2 1$lsHeap.20190718.133405.15554.0.001.heapsnapshotcopy

--heap-prof#

Starts the V8 heap profiler on start up, and writes the heap profile to diskbefore exit.

If--heap-prof-dir is not specified, the generated profile is placedin the current working directory.

If--heap-prof-name is not specified, the generated profile isnamedHeap.${yyyymmdd}.${hhmmss}.${pid}.${tid}.${seq}.heapprofile.

$node --heap-prof index.js$ls *.heapprofileHeap.20190409.202950.15293.0.001.heapprofilecopy

--heap-prof-dir#

Specify the directory where the heap profiles generated by--heap-prof willbe placed.

The default value is controlled by the--diagnostic-dir command-line option.

--heap-prof-interval#

Specify the average sampling interval in bytes for the heap profiles generatedby--heap-prof. The default is 512 * 1024 bytes.

--heap-prof-name#

Specify the file name of the heap profile generated by--heap-prof.

--icu-data-dir=file#

Specify ICU data load path. (OverridesNODE_ICU_DATA.)

--import=module#

Preload the specified module at startup.

FollowsECMAScript module resolution rules.Use--require to load aCommonJS module.Modules preloaded with--require will run before modules preloaded with--import.

--input-type=type#

This configures Node.js to interpret string input as CommonJS or as an ESmodule. String input is input via--eval,--print, orSTDIN.

Valid values are"commonjs" and"module". The default is"commonjs".

The REPL does not support this option.

--inspect-brk[=[host:]port]#

Activate inspector onhost:port and break at start of user script.Defaulthost:port is127.0.0.1:9229.

--inspect-port=[host:]port#

Set thehost:port to be used when the inspector is activated.Useful when activating the inspector by sending theSIGUSR1 signal.

Default host is127.0.0.1.

See thesecurity warning below regarding thehostparameter usage.

--inspect[=[host:]port]#

Activate inspector onhost:port. Default is127.0.0.1:9229.

V8 inspector integration allows tools such as Chrome DevTools and IDEs to debugand profile Node.js instances. The tools attach to Node.js instances via atcp port and communicate using theChrome DevTools Protocol.

Warning: binding inspector to a public IP:port combination is insecure#

Binding the inspector to a public IP (including0.0.0.0) with an open port isinsecure, as it allows external hosts to connect to the inspector and performaremote code execution attack.

If specifying a host, make sure that either:

• The host is not accessible from public networks.
• A firewall disallows unwanted connections on the port.

More specifically,--inspect=0.0.0.0 is insecure if the port (9229 bydefault) is not firewall-protected.

See thedebugging security implications section for more information.

--inspect-publish-uid=stderr,http#

Specify ways of the inspector web socket url exposure.

By default inspector websocket url is available in stderr and under/json/listendpoint onhttp://host:port/json/list.

--insecure-http-parser#

Use an insecure HTTP parser that accepts invalid HTTP headers. This may allowinteroperability with non-conformant HTTP implementations. It may also allowrequest smuggling and other HTTP attacks that rely on invalid headers beingaccepted. Avoid using this option.

--jitless#

Disableruntime allocation of executable memory. This may berequired on some platforms for security reasons. It can also reduce attacksurface on other platforms, but the performance impact may be severe.

This flag is inherited from V8 and is subject to change upstream. It maydisappear in a non-semver-major release.

--max-http-header-size=size#

Specify the maximum size, in bytes, of HTTP headers. Defaults to 16 KiB.

--napi-modules#

This option is a no-op. It is kept for compatibility.

--no-addons#

Disable thenode-addons exports condition as well as disable loadingnative addons. When--no-addons is specified, callingprocess.dlopen orrequiring a native C++ addon will fail and throw an exception.

--no-deprecation#

Silence deprecation warnings.

--no-extra-info-on-fatal-exception#

Hide extra information on fatal exception that causes exit.

--no-force-async-hooks-checks#

Disables runtime checks forasync_hooks. These will still be enableddynamically whenasync_hooks is enabled.

--no-global-search-paths#

Do not search modules from global paths like$HOME/.node_modules and$NODE_PATH.

--no-warnings#

Silence all process warnings (including deprecations).

--node-memory-debug#

Enable extra debug checks for memory leaks in Node.js internals. This isusually only useful for developers debugging Node.js itself.

--openssl-config=file#

Load an OpenSSL configuration file on startup. Among other uses, this can beused to enable FIPS-compliant crypto if Node.js is builtagainst FIPS-enabled OpenSSL.

--openssl-shared-config#

Enable OpenSSL default configuration section,openssl_conf to be read fromthe OpenSSL configuration file. The default configuration file is namedopenssl.cnf but this can be changed using the environment variableOPENSSL_CONF, or by using the command line option--openssl-config.The location of the default OpenSSL configuration file depends on how OpenSSLis being linked to Node.js. Sharing the OpenSSL configuration may have unwantedimplications and it is recommended to use a configuration section specific toNode.js which isnodejs_conf and is default when this option is not used.

--openssl-legacy-provider#

Enable OpenSSL 3.0 legacy provider. For more information please seeOSSL_PROVIDER-legacy.

--pending-deprecation#

Emit pending deprecation warnings.

Pending deprecations are generally identical to a runtime deprecation with thenotable exception that they are turnedoff by default and will not be emittedunless either the--pending-deprecation command-line flag, or theNODE_PENDING_DEPRECATION=1 environment variable, is set. Pending deprecationsare used to provide a kind of selective "early warning" mechanism thatdevelopers may leverage to detect deprecated API usage.

--policy-integrity=sri#

Instructs Node.js to error prior to running any code if the policy does not havethe specified integrity. It expects aSubresource Integrity string as aparameter.

--preserve-symlinks#

Instructs the module loader to preserve symbolic links when resolving andcaching modules.

By default, when Node.js loads a module from a path that is symbolically linkedto a different on-disk location, Node.js will dereference the link and use theactual on-disk "real path" of the module as both an identifier and as a rootpath to locate other dependency modules. In most cases, this default behavioris acceptable. However, when using symbolically linked peer dependencies, asillustrated in the example below, the default behavior causes an exception tobe thrown ifmoduleA attempts to requiremoduleB as a peer dependency:

{appDir} ├── app │   ├── index.js │   └── node_modules │       ├── moduleA -> {appDir}/moduleA │       └── moduleB │           ├── index.js │           └── package.json └── moduleA     ├── index.js     └── package.jsoncopy

The--preserve-symlinks command-line flag instructs Node.js to use thesymlink path for modules as opposed to the real path, allowing symbolicallylinked peer dependencies to be found.

Note, however, that using--preserve-symlinks can have other side effects.Specifically, symbolically linkednative modules can fail to load if thoseare linked from more than one location in the dependency tree (Node.js wouldsee those as two separate modules and would attempt to load the module multipletimes, causing an exception to be thrown).

The--preserve-symlinks flag does not apply to the main module, which allowsnode --preserve-symlinks node_module/.bin/<foo> to work. To apply the samebehavior for the main module, also use--preserve-symlinks-main.

--preserve-symlinks-main#

Instructs the module loader to preserve symbolic links when resolving andcaching the main module (require.main).

This flag exists so that the main module can be opted-in to the same behaviorthat--preserve-symlinks gives to all other imports; they are separate flags,however, for backward compatibility with older Node.js versions.

--preserve-symlinks-main does not imply--preserve-symlinks; use--preserve-symlinks-main in addition to--preserve-symlinks when it is not desirable to follow symlinks beforeresolving relative paths.

See--preserve-symlinks for more information.

--prof#

Generate V8 profiler output.

--prof-process#

Process V8 profiler output generated using the V8 option--prof.

--redirect-warnings=file#

Write process warnings to the given file instead of printing to stderr. Thefile will be created if it does not exist, and will be appended to if it does.If an error occurs while attempting to write the warning to the file, thewarning will be written to stderr instead.

Thefile name may be an absolute path. If it is not, the default directory itwill be written to is controlled by the--diagnostic-dir command-line option.

--report-compact#

Write reports in a compact format, single-line JSON, more easily consumableby log processing systems than the default multi-line format designed forhuman consumption.

--report-dir=directory,report-directory=directory#

Location at which the report will be generated.

--report-filename=filename#

Name of the file to which the report will be written.

If the filename is set to'stdout' or'stderr', the report is written tothe stdout or stderr of the process respectively.

--report-on-fatalerror#

Enables the report to be triggered on fatal errors (internal errors withinthe Node.js runtime such as out of memory) that lead to termination of theapplication. Useful to inspect various diagnostic data elements such as heap,stack, event loop state, resource consumption etc. to reason about the fatalerror.

--report-on-signal#

Enables report to be generated upon receiving the specified (or predefined)signal to the running Node.js process. The signal to trigger the report isspecified through--report-signal.

--report-signal=signal#

Sets or resets the signal for report generation (not supported on Windows).Default signal isSIGUSR2.

--report-uncaught-exception#

Enables report to be generated when the process exits due to an uncaughtexception. Useful when inspecting the JavaScript stack in conjunction withnative stack and other runtime environment data.

--secure-heap=n#

Initializes an OpenSSL secure heap ofn bytes. When initialized, thesecure heap is used for selected types of allocations within OpenSSLduring key generation and other operations. This is useful, for instance,to prevent sensitive information from leaking due to pointer overrunsor underruns.

The secure heap is a fixed size and cannot be resized at runtime so,if used, it is important to select a large enough heap to cover allapplication uses.

The heap size given must be a power of two. Any value less than 2will disable the secure heap.

The secure heap is disabled by default.

The secure heap is not available on Windows.

SeeCRYPTO_secure_malloc_init for more details.

--secure-heap-min=n#

When using--secure-heap, the--secure-heap-min flag specifies theminimum allocation from the secure heap. The minimum value is2.The maximum value is the lesser of--secure-heap or2147483647.The value given must be a power of two.

--snapshot-blob=path#

When used with--build-snapshot,--snapshot-blob specifies the pathwhere the generated snapshot blob is written to. If not specified, thegenerated blob is written tosnapshot.blob in the current working directory.

When used without--build-snapshot,--snapshot-blob specifies thepath to the blob that is used to restore the application state.

When loading a snapshot, Node.js checks that:

1. The version, architecture, and platform of the running Node.js binaryare exactly the same as that of the binary that generates the snapshot.
2. The V8 flags and CPU features are compatible with that of the binarythat generates the snapshot.

If they don't match, Node.js refuses to load the snapshot and exits withstatus code 1.

--test#

Starts the Node.js command line test runner. This flag cannot be combined with--watch-path,--check,--eval,--interactive, or the inspector.See the documentation onrunning tests from the command linefor more details.

--test-concurrency#

The maximum number of test files that the test runner CLI will executeconcurrently. The default value isos.availableParallelism() - 1.

--test-name-pattern#

A regular expression that configures the test runner to only execute testswhose name matches the provided pattern. See the documentation onfiltering tests by name for more details.

--test-reporter#

A test reporter to use when running tests. See the documentation ontest reporters for more details.

--test-reporter-destination#

The destination for the corresponding test reporter. See the documentation ontest reporters for more details.

--test-only#

Configures the test runner to only execute top level tests that have theonlyoption set.

--test-shard#

Test suite shard to execute in a format of<index>/<total>, where

index is a positive integer, index of divided partstotal is a positive integer, total of divided partThis command will divide all tests files intototal equal parts,and will run only those that happen to be in anindex part.

For example, to split your tests suite into three parts, use this:

node --test --test-shard=1/3node --test --test-shard=2/3node --test --test-shard=3/3copy

--throw-deprecation#

Throw errors for deprecations.

--title=title#

Setprocess.title on startup.

--tls-cipher-list=list#

Specify an alternative default TLS cipher list. Requires Node.js to be builtwith crypto support (default).

--tls-keylog=file#

Log TLS key material to a file. The key material is in NSSSSLKEYLOGFILEformat and can be used by software (such as Wireshark) to decrypt the TLStraffic.

--tls-max-v1.2#

Settls.DEFAULT_MAX_VERSION to 'TLSv1.2'. Use to disable support forTLSv1.3.

--tls-max-v1.3#

Set defaulttls.DEFAULT_MAX_VERSION to 'TLSv1.3'. Use to enable supportfor TLSv1.3.

--tls-min-v1.0#

Set defaulttls.DEFAULT_MIN_VERSION to 'TLSv1'. Use for compatibility withold TLS clients or servers.

--tls-min-v1.1#

Set defaulttls.DEFAULT_MIN_VERSION to 'TLSv1.1'. Use for compatibilitywith old TLS clients or servers.

--tls-min-v1.2#

Set defaulttls.DEFAULT_MIN_VERSION to 'TLSv1.2'. This is the default for12.x and later, but the option is supported for compatibility with older Node.jsversions.

--tls-min-v1.3#

Set defaulttls.DEFAULT_MIN_VERSION to 'TLSv1.3'. Use to disable supportfor TLSv1.2, which is not as secure as TLSv1.3.

--trace-atomics-wait#

Print short summaries of calls toAtomics.wait() to stderr.The output could look like this:

(node:15701) [Thread 0] Atomics.wait(<address> + 0, 1, inf) started(node:15701) [Thread 0] Atomics.wait(<address> + 0, 1, inf) did not wait because the values mismatched(node:15701) [Thread 0] Atomics.wait(<address> + 0, 0, 10) started(node:15701) [Thread 0] Atomics.wait(<address> + 0, 0, 10) timed out(node:15701) [Thread 0] Atomics.wait(<address> + 4, 0, inf) started(node:15701) [Thread 1] Atomics.wait(<address> + 4, -1, inf) started(node:15701) [Thread 0] Atomics.wait(<address> + 4, 0, inf) was woken up by another thread(node:15701) [Thread 1] Atomics.wait(<address> + 4, -1, inf) was woken up by another threadcopy

The fields here correspond to:

• The thread id as given byworker_threads.threadId
• The base address of theSharedArrayBuffer in question, as well as thebyte offset corresponding to the index passed toAtomics.wait()
• The expected value that was passed toAtomics.wait()
• The timeout passed toAtomics.wait

--trace-deprecation#

Print stack traces for deprecations.

--trace-event-categories#

A comma separated list of categories that should be traced when trace eventtracing is enabled using--trace-events-enabled.

--trace-event-file-pattern#

Template string specifying the filepath for the trace event data, itsupports${rotation} and${pid}.

--trace-events-enabled#

Enables the collection of trace event tracing information.

--trace-exit#

Prints a stack trace whenever an environment is exited proactively,i.e. invokingprocess.exit().

--trace-sigint#

Prints a stack trace on SIGINT.

--trace-sync-io#

Prints a stack trace whenever synchronous I/O is detected after the first turnof the event loop.

--trace-tls#

Prints TLS packet trace information tostderr. This can be used to debug TLSconnection problems.

--trace-uncaught#

Print stack traces for uncaught exceptions; usually, the stack trace associatedwith the creation of anError is printed, whereas this makes Node.js alsoprint the stack trace associated with throwing the value (which does not needto be anError instance).

Enabling this option may affect garbage collection behavior negatively.

--trace-warnings#

Print stack traces for process warnings (including deprecations).

--track-heap-objects#

Track heap object allocations for heap snapshots.

--unhandled-rejections=mode#

Using this flag allows to change what should happen when an unhandled rejectionoccurs. One of the following modes can be chosen:

• throw: EmitunhandledRejection. If this hook is not set, raise theunhandled rejection as an uncaught exception. This is the default.
• strict: Raise the unhandled rejection as an uncaught exception. If theexception is handled,unhandledRejection is emitted.
• warn: Always trigger a warning, no matter if theunhandledRejectionhook is set or not but do not print the deprecation warning.
• warn-with-error-code: EmitunhandledRejection. If this hook is notset, trigger a warning, and set the process exit code to 1.
• none: Silence all warnings.

If a rejection happens during the command line entry point's ES module staticloading phase, it will always raise it as an uncaught exception.

--use-bundled-ca,--use-openssl-ca#

Use bundled Mozilla CA store as supplied by current Node.js versionor use OpenSSL's default CA store. The default store is selectableat build-time.

The bundled CA store, as supplied by Node.js, is a snapshot of Mozilla CA storethat is fixed at release time. It is identical on all supported platforms.

Using OpenSSL store allows for external modifications of the store. For mostLinux and BSD distributions, this store is maintained by the distributionmaintainers and system administrators. OpenSSL CA store location is dependent onconfiguration of the OpenSSL library but this can be altered at runtime usingenvironment variables.

SeeSSL_CERT_DIR andSSL_CERT_FILE.

--use-largepages=mode#

Re-map the Node.js static code to large memory pages at startup. If supported onthe target system, this will cause the Node.js static code to be moved onto 2MiB pages instead of 4 KiB pages.

The following values are valid formode:

• off: No mapping will be attempted. This is the default.
• on: If supported by the OS, mapping will be attempted. Failure to map willbe ignored and a message will be printed to standard error.
• silent: If supported by the OS, mapping will be attempted. Failure to mapwill be ignored and will not be reported.

--v8-options#

Print V8 command-line options.

--v8-pool-size=num#

Set V8's thread pool size which will be used to allocate background jobs.

If set to0 then Node.js will choose an appropriate size of the thread poolbased on an estimate of the amount of parallelism.

The amount of parallelism refers to the number of computations that can becarried out simultaneously in a given machine. In general, it's the same as theamount of CPUs, but it may diverge in environments such as VMs or containers.

--watch#

Starts Node.js in watch mode.When in watch mode, changes in the watched files cause the Node.js process torestart.By default, watch mode will watch the entry pointand any required or imported module.Use--watch-path to specify what paths to watch.

This flag cannot be combined with--check,--eval,--interactive, or the REPL.

$node --watch index.jscopy

--watch-path#

Starts Node.js in watch mode and specifies what paths to watch.When in watch mode, changes in the watched paths cause the Node.js process torestart.This will turn off watching of required or imported modules, even when used incombination with--watch.

This flag cannot be combined with--check,--eval,--interactive,--test, or the REPL.

$node --watch-path=./src --watch-path=./tests index.jscopy

This option is only supported on macOS and Windows.AnERR_FEATURE_UNAVAILABLE_ON_PLATFORM exception will be thrownwhen the option is used on a platform that does not support it.

--watch-preserve-output#

Disable the clearing of the console when watch mode restarts the process.

$node --watch --watch-preserve-output test.jscopy

--zero-fill-buffers#

Automatically zero-fills all newly allocatedBuffer andSlowBufferinstances.

-c,--check#

Syntax check the script without executing.

-e,--eval "script"#

Evaluate the following argument as JavaScript. The modules which arepredefined in the REPL can also be used inscript.

On Windows, usingcmd.exe a single quote will not work correctly because itonly recognizes double" for quoting. In Powershell or Git bash, both'and" are usable.

-h,--help#

Print node command-line options.The output of this option is less detailed than this document.

-i,--interactive#

Opens the REPL even if stdin does not appear to be a terminal.

-p,--print "script"#

Identical to-e but prints the result.

-r,--require module#

Preload the specified module at startup.

Followsrequire()'s module resolutionrules.module may be either a path to a file, or a node module name.

Only CommonJS modules are supported.Use--import to preload anECMAScript module.Modules preloaded with--require will run before modules preloaded with--import.

-v,--version#

Print node's version.

Environment variables#

FORCE_COLOR=[1, 2, 3]#

TheFORCE_COLOR environment variable is used toenable ANSI colorized output. The value may be:

• 1,true, or the empty string'' indicate 16-color support,
• 2 to indicate 256-color support, or
• 3 to indicate 16 million-color support.

WhenFORCE_COLOR is used and set to a supported value, both theNO_COLOR,andNODE_DISABLE_COLORS environment variables are ignored.

Any other value will result in colorized output being disabled.

NODE_DEBUG=module[,…]#

','-separated list of core modules that should print debug information.

NODE_DEBUG_NATIVE=module[,…]#

','-separated list of core C++ modules that should print debug information.

NODE_DISABLE_COLORS=1#

When set, colors will not be used in the REPL.

NODE_EXTRA_CA_CERTS=file#

When set, the well known "root" CAs (like VeriSign) will be extended with theextra certificates infile. The file should consist of one or more trustedcertificates in PEM format. A message will be emitted (once) withprocess.emitWarning() if the file is missing ormalformed, but any errors are otherwise ignored.

Neither the well known nor extra certificates are used when thecaoptions property is explicitly specified for a TLS or HTTPS client or server.

This environment variable is ignored whennode runs as setuid root orhas Linux file capabilities set.

TheNODE_EXTRA_CA_CERTS environment variable is only read when the Node.jsprocess is first launched. Changing the value at runtime usingprocess.env.NODE_EXTRA_CA_CERTS has no effect on the current process.

NODE_ICU_DATA=file#

Data path for ICU (Intl object) data. Will extend linked-in data when compiledwith small-icu support.

NODE_NO_WARNINGS=1#

When set to1, process warnings are silenced.

NODE_OPTIONS=options...#

A space-separated list of command-line options.options... are interpretedbefore command-line options, so command-line options will override orcompound after anything inoptions.... Node.js will exit with an error ifan option that is not allowed in the environment is used, such as-p or ascript file.

If an option value contains a space, it can be escaped using double quotes:

NODE_OPTIONS='--require "./my path/file.js"'copy

A singleton flag passed as a command-line option will override the same flagpassed intoNODE_OPTIONS:

# The inspector will be available on port 5555NODE_OPTIONS='--inspect=localhost:4444' node --inspect=localhost:5555copy

A flag that can be passed multiple times will be treated as if itsNODE_OPTIONS instances were passed first, and then its command-lineinstances afterwards:

NODE_OPTIONS='--require "./a.js"' node --require"./b.js"# is equivalent to:node --require"./a.js" --require"./b.js"copy

Node.js options that are allowed are:

• --conditions,-C
• --diagnostic-dir
• --disable-proto
• --dns-result-order
• --enable-fips
• --enable-network-family-autoselection
• --enable-source-maps
• --experimental-abortcontroller
• --experimental-default-type
• --experimental-global-customevent
• --experimental-global-webcrypto
• --experimental-import-meta-resolve
• --experimental-json-modules
• --experimental-loader
• --experimental-modules
• --experimental-network-imports
• --experimental-policy
• --experimental-shadow-realm
• --experimental-specifier-resolution
• --experimental-top-level-await
• --experimental-vm-modules
• --experimental-wasi-unstable-preview1
• --experimental-wasm-modules
• --force-context-aware
• --force-fips
• --force-node-api-uncaught-exceptions-policy
• --frozen-intrinsics
• --heapsnapshot-near-heap-limit
• --heapsnapshot-signal
• --http-parser
• --icu-data-dir
• --import
• --input-type
• --insecure-http-parser
• --inspect-brk
• --inspect-port,--debug-port
• --inspect-publish-uid
• --inspect
• --max-http-header-size
• --napi-modules
• --no-addons
• --no-deprecation
• --no-experimental-fetch
• --no-experimental-repl-await
• --no-extra-info-on-fatal-exception
• --no-force-async-hooks-checks
• --no-global-search-paths
• --no-warnings
• --node-memory-debug
• --openssl-config
• --openssl-legacy-provider
• --openssl-shared-config
• --pending-deprecation
• --policy-integrity
• --preserve-symlinks-main
• --preserve-symlinks
• --prof-process
• --redirect-warnings
• --report-compact
• --report-dir,--report-directory
• --report-filename
• --report-on-fatalerror
• --report-on-signal
• --report-signal
• --report-uncaught-exception
• --require,-r
• --secure-heap-min
• --secure-heap
• --snapshot-blob
• --test-only
• --test-reporter-destination
• --test-reporter
• --test-shard
• --throw-deprecation
• --title
• --tls-cipher-list
• --tls-keylog
• --tls-max-v1.2
• --tls-max-v1.3
• --tls-min-v1.0
• --tls-min-v1.1
• --tls-min-v1.2
• --tls-min-v1.3
• --trace-atomics-wait
• --trace-deprecation
• --trace-event-categories
• --trace-event-file-pattern
• --trace-events-enabled
• --trace-exit
• --trace-sigint
• --trace-sync-io
• --trace-tls
• --trace-uncaught
• --trace-warnings
• --track-heap-objects
• --unhandled-rejections
• --use-bundled-ca
• --use-largepages
• --use-openssl-ca
• --v8-pool-size
• --watch-path
• --watch-preserve-output
• --watch
• --zero-fill-buffers

V8 options that are allowed are:

• --abort-on-uncaught-exception
• --disallow-code-generation-from-strings
• --enable-etw-stack-walking
• --huge-max-old-generation-size
• --interpreted-frames-native-stack
• --jitless
• --max-old-space-size
• --max-semi-space-size
• --perf-basic-prof-only-functions
• --perf-basic-prof
• --perf-prof-unwinding-info
• --perf-prof
• --stack-trace-limit

--perf-basic-prof-only-functions,--perf-basic-prof,--perf-prof-unwinding-info, and--perf-prof are only available on Linux.

--enable-etw-stack-walking is only available on Windows.

NODE_PATH=path[:…]#

':'-separated list of directories prefixed to the module search path.

On Windows, this is a';'-separated list instead.

NODE_PENDING_DEPRECATION=1#

When set to1, emit pending deprecation warnings.

Pending deprecations are generally identical to a runtime deprecation with thenotable exception that they are turnedoff by default and will not be emittedunless either the--pending-deprecation command-line flag, or theNODE_PENDING_DEPRECATION=1 environment variable, is set. Pending deprecationsare used to provide a kind of selective "early warning" mechanism thatdevelopers may leverage to detect deprecated API usage.

NODE_PENDING_PIPE_INSTANCES=instances#

Set the number of pending pipe instance handles when the pipe server is waitingfor connections. This setting applies to Windows only.

NODE_PRESERVE_SYMLINKS=1#

When set to1, instructs the module loader to preserve symbolic links whenresolving and caching modules.

NODE_REDIRECT_WARNINGS=file#

When set, process warnings will be emitted to the given file instead ofprinting to stderr. The file will be created if it does not exist, and will beappended to if it does. If an error occurs while attempting to write thewarning to the file, the warning will be written to stderr instead. This isequivalent to using the--redirect-warnings=file command-line flag.

NODE_REPL_HISTORY=file#

Path to the file used to store the persistent REPL history. The default path is~/.node_repl_history, which is overridden by this variable. Setting the valueto an empty string ('' or' ') disables persistent REPL history.

NODE_REPL_EXTERNAL_MODULE=file#

Path to a Node.js module which will be loaded in place of the built-in REPL.Overriding this value to an empty string ('') will use the built-in REPL.

NODE_SKIP_PLATFORM_CHECK=value#

Ifvalue equals'1', the check for a supported platform is skipped duringNode.js startup. Node.js might not execute correctly. Any issues encounteredon unsupported platforms will not be fixed.

NODE_TEST_CONTEXT=value#

Ifvalue equals'child', test reporter options will be overridden and testoutput will be sent to stdout in the TAP format. If any other value is provided,Node.js makes no guarantees about the reporter format used or its stability.

NODE_TLS_REJECT_UNAUTHORIZED=value#

Ifvalue equals'0', certificate validation is disabled for TLS connections.This makes TLS, and HTTPS by extension, insecure. The use of this environmentvariable is strongly discouraged.

NODE_V8_COVERAGE=dir#

When set, Node.js will begin outputtingV8 JavaScript code coverage andSource Map data to the directory provided as an argument (coverageinformation is written as JSON to files with acoverage prefix).

NODE_V8_COVERAGE will automatically propagate to subprocesses, making iteasier to instrument applications that call thechild_process.spawn() familyof functions.NODE_V8_COVERAGE can be set to an empty string, to preventpropagation.

Coverage output#

Coverage is output as an array ofScriptCoverage objects on the top-levelkeyresult:

{"result":[{"scriptId":"67","url":"internal/tty.js","functions":[]}]}copy

Source map cache#

If found, source map data is appended to the top-level keysource-map-cacheon the JSON coverage object.

source-map-cache is an object with keys representing the files source mapswere extracted from, and values which include the raw source-map URL(in the keyurl), the parsed Source Map v3 information (in the keydata),and the line lengths of the source file (in the keylineLengths).

{"result":[{"scriptId":"68","url":"file:///absolute/path/to/source.js","functions":[]}],"source-map-cache":{"file:///absolute/path/to/source.js":{"url":"./path-to-map.json","data":{"version":3,"sources":["file:///absolute/path/to/original.js"],"names":["Foo","console","info"],"mappings":"MAAMA,IACJC,YAAaC","sourceRoot":"./"},"lineLengths":[13,62,38,27]}}}copy

NO_COLOR=<any>#

NO_COLOR is an alias forNODE_DISABLE_COLORS. The value of theenvironment variable is arbitrary.

OPENSSL_CONF=file#

Load an OpenSSL configuration file on startup. Among other uses, this can beused to enable FIPS-compliant crypto if Node.js is built with./configure --openssl-fips.

If the--openssl-config command-line option is used, the environmentvariable is ignored.

SSL_CERT_DIR=dir#

If--use-openssl-ca is enabled, this overrides and sets OpenSSL's directorycontaining trusted certificates.

Be aware that unless the child environment is explicitly set, this environmentvariable will be inherited by any child processes, and if they use OpenSSL, itmay cause them to trust the same CAs as node.

SSL_CERT_FILE=file#

If--use-openssl-ca is enabled, this overrides and sets OpenSSL's filecontaining trusted certificates.

Be aware that unless the child environment is explicitly set, this environmentvariable will be inherited by any child processes, and if they use OpenSSL, itmay cause them to trust the same CAs as node.

TZ#

TheTZ environment variable is used to specify the timezone configuration.

While Node.js does not support all of the variousways thatTZ is handled inother environments, it does support basictimezone IDs (such as'Etc/UTC','Europe/Paris', or'America/New_York').It may support a few other abbreviations or aliases, but these are stronglydiscouraged and not guaranteed.

$TZ=Europe/Dublin node -pe"new Date().toString()"Wed May 12 2021 20:30:48 GMT+0100 (Irish Standard Time)copy

UV_THREADPOOL_SIZE=size#

Set the number of threads used in libuv's threadpool tosize threads.

Asynchronous system APIs are used by Node.js whenever possible, but where theydo not exist, libuv's threadpool is used to create asynchronous node APIs basedon synchronous system APIs. Node.js APIs that use the threadpool are:

• allfs APIs, other than the file watcher APIs and those that are explicitlysynchronous
• asynchronous crypto APIs such ascrypto.pbkdf2(),crypto.scrypt(),crypto.randomBytes(),crypto.randomFill(),crypto.generateKeyPair()
• dns.lookup()
• allzlib APIs, other than those that are explicitly synchronous

Because libuv's threadpool has a fixed size, it means that if for whateverreason any of these APIs takes a long time, other (seemingly unrelated) APIsthat run in libuv's threadpool will experience degraded performance. In order tomitigate this issue, one potential solution is to increase the size of libuv'sthreadpool by setting the'UV_THREADPOOL_SIZE' environment variable to a valuegreater than4 (its current default value). For more information, see thelibuv threadpool documentation.

Useful V8 options#

V8 has its own set of CLI options. Any V8 CLI option that is provided tonodewill be passed on to V8 to handle. V8's options haveno stability guarantee.The V8 team themselves don't consider them to be part of their formal API,and reserve the right to change them at any time. Likewise, they are notcovered by the Node.js stability guarantees. Many of the V8options are of interest only to V8 developers. Despite this, there is a smallset of V8 options that are widely applicable to Node.js, and they aredocumented here:

--max-old-space-size=SIZE (in megabytes)#

Sets the max memory size of V8's old memory section. As memoryconsumption approaches the limit, V8 will spend more time ongarbage collection in an effort to free unused memory.

On a machine with 2 GiB of memory, consider setting this to1536 (1.5 GiB) to leave some memory for other uses and avoid swapping.

$node --max-old-space-size=1536 index.jscopy

--max-semi-space-size=SIZE (in megabytes)#

Sets the maximumsemi-space size for V8'sscavenge garbage collector inMiB (megabytes).Increasing the max size of a semi-space may improve throughput for Node.js atthe cost of more memory consumption.

Since the young generation size of the V8 heap is three times (seeYoungGenerationSizeFromSemiSpaceSize in V8) the size of the semi-space,an increase of 1 MiB to semi-space applies to each of the three individualsemi-spaces and causes the heap size to increase by 3 MiB. The throughputimprovement depends on your workload (see#42511).

The default value is 16 MiB for 64-bit systems and 8 MiB for 32-bit systems. Toget the best configuration for your application, you should try differentmax-semi-space-size values when running benchmarks for your application.

For example, benchmark on a 64-bit systems:

for MiBin 16 32 64 128;do    node --max-semi-space-size=$MiB index.jsdonecopy