.Dd $Mdocdate$

.Nm node

.Nd server-side JavaScript runtime

.Nm node

.Op Ar options

.Op Ar v8 options

.Op Ar <program-entry-point> | Fl e Ar string | Fl -

.Op Ar arguments ...

.Nm node

.Cm inspect,

.Op Ar <program-entry-point> | Fl e Ar string | Ar <host>:<port>

.Ar ...

.Nm node

.Op Fl -v8-options

Node.js is a set of libraries for JavaScript which allows it to be used outside of the browser.

It is primarily focused on creating simple, easy-to-build network clients and servers.

.Pp

Execute

.Nm

without arguments to start a REPL.

.Bl -tag -width 6n

.It Fl

Alias for stdin. Analogous to the use of \fB-\fR in other command-line utilities,

meaning that the script is read from stdin, and the rest of the options

are passed to that script.

.It Fl -

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, then

the next argument is used as a script filename.

.It Fl -abort-on-uncaught-exception

Aborting instead of exiting causes a core file to be generated for post-mortem

analysis using a debugger (such as \fBlldb\fR, \fBgdb\fR, and \fBmdb\fR).

If this flag is passed, the behavior can still be set to not abort through

\fBprocess.setUncaughtExceptionCaptureCallback()\fR (and through usage of the

\fBnode:domain\fR module that uses it).

.It Fl -allow-addons

When using the Permission Model, the process will not be able to use

native addons by default.

Attempts to do so will throw an \fBERR_DLOPEN_DISABLED\fR unless the

user explicitly passes the \fB--allow-addons\fR flag when starting Node.js.

Example:

.Bd -literal

// Attempt to require an native addon

require('nodejs-addon-example');

.Ed

.Bd -literal

$ node --permission --allow-fs-read=* index.js

node:internal/modules/cjs/loader:1319

return process.dlopen(module, path.toNamespacedPath(filename));

^

Error: Cannot load native addon because loading addons is disabled.

at Module._extensions..node (node:internal/modules/cjs/loader:1319:18)

at Module.load (node:internal/modules/cjs/loader:1091:32)

at Module._load (node:internal/modules/cjs/loader:938:12)

at Module.require (node:internal/modules/cjs/loader:1115:19)

at require (node:internal/modules/helpers:130:18)

at Object.<anonymous> (/home/index.js:1:15)

at Module._compile (node:internal/modules/cjs/loader:1233:14)

at Module._extensions..js (node:internal/modules/cjs/loader:1287:10)

at Module.load (node:internal/modules/cjs/loader:1091:32)

at Module._load (node:internal/modules/cjs/loader:938:12) {

code: 'ERR_DLOPEN_DISABLED'

}

.Ed

.It Fl -allow-child-process

When using the Permission Model, the process will not be able to spawn any

child process by default.

Attempts to do so will throw an \fBERR_ACCESS_DENIED\fR unless the

user explicitly passes the \fB--allow-child-process\fR flag when starting Node.js.

Example:

.Bd -literal

const childProcess = require('node:child_process');

// Attempt to bypass the permission

childProcess.spawn('node', ['-e', 'require("fs").writeFileSync("/new-file", "example")']);

.Ed

.Bd -literal

$ node --permission --allow-fs-read=* index.js

node:internal/child_process:388

const err = this._handle.spawn(options);

^

Error: Access to this API has been restricted

at ChildProcess.spawn (node:internal/child_process:388:28)

at node:internal/main/run_main_module:17:47 {

code: 'ERR_ACCESS_DENIED',

permission: 'ChildProcess'

}

.Ed

The \fBchild_process.fork()\fR API inherits the execution arguments from the

parent process. This means that if Node.js is started with the Permission

Model enabled and the \fB--allow-child-process\fR flag is set, any child process

created using \fBchild_process.fork()\fR will automatically receive all relevant

Permission Model flags.

This behavior also applies to \fBchild_process.spawn()\fR, but in that case, the

flags are propagated via the \fBNODE_OPTIONS\fR environment variable rather than

directly through the process arguments.

.It Fl -allow-env

When using the Permission Model, the process starts without the environment

variables it has not been granted access to. At startup, every variable that

\fB--allow-env\fR does not match is removed from the process environment. Removed

variables are absent from \fBprocess.env\fR, from diagnostic reports, from native

code calling \fBgetenv()\fR, and from the environment of child processes and worker

threads.

The valid values are:

.Bl -bullet

.It

\fB*\fR - Grants access to every environment variable.

.It

A variable name, for example \fB--allow-env=DATABASE_URL\fR.

.It

A variable name prefix followed by \fB*\fR, for example \fB--allow-env=APP_*\fR.

.El

Multiple values can be passed by repeating the flag, or by separating them with

commas: \fB--allow-env=PORT,APP_*\fR. Variable names are case-insensitive on

Windows.

Example:

.Bd -literal

console.log(process.env.DATABASE_URL);

console.log(process.env.AWS_SECRET_ACCESS_KEY);

.Ed

.Bd -literal

$ node --permission --allow-fs-read=* --allow-env=DATABASE_URL index.js

postgres://localhost/app

undefined

(node:1234) Warning: The permission model removed the environment variable "AWS_SECRET_ACCESS_KEY" at startup. Use --allow-env to manage permissions.

.Ed

The variables that Node.js and its bundled dependencies read, such as

\fBNODE_OPTIONS\fR, \fBPATH\fR, \fBHOME\fR, \fBTZ\fR, and \fBSSL_CERT_FILE\fR, are always kept, as

are the variables defined in \fB--env-file\fR files. \fBNODE_ENV\fR is not kept

by default, so applications and libraries that read it need

\fB--allow-env=NODE_ENV\fR. See Environment variable permissions for details.

.It Fl -allow-ffi

When using the Permission Model, the process will not be able to use FFI

APIs by default. Attempts to use FFI APIs will throw an \fBERR_ACCESS_DENIED\fR

exception unless the user explicitly passes the \fB--allow-ffi\fR flag when

starting Node.js. The \fBnode:ffi\fR module is only available in builds with

FFI support.

Example:

.Bd -literal

const { DynamicLibrary, suffix } = require('node:ffi');

const lib = new DynamicLibrary(`./mylib.${suffix}`);

.Ed

.Bd -literal

$ node --permission index.js

Error: Access to this API has been restricted. Use --allow-ffi to manage permissions.

at node:internal/main/run_main_module:17:47 {

code: 'ERR_ACCESS_DENIED',

permission: 'FFI'

}

.Ed

.It Fl -allow-fs-read

This flag configures file system read permissions using

the Permission Model.

The valid arguments for the \fB--allow-fs-read\fR flag are:

.Bl -bullet

.It

\fB*\fR - To allow all \fBFileSystemRead\fR operations.

.It

Multiple paths can be allowed using multiple \fB--allow-fs-read\fR flags.

Example \fB--allow-fs-read=/folder1/ --allow-fs-read=/folder2/\fR

.El

Examples can be found in the File System Permissions documentation.

The initializer module and custom \fB--require\fR modules has a implicit

read permission.

.Bd -literal

$ node --permission -r custom-require.js -r custom-require-2.js index.js

.Ed

.Bl -bullet

.It

The \fBcustom-require.js\fR, \fBcustom-require-2.js\fR, and \fBindex.js\fR will be

by default in the allowed read list.

.El

.Bd -literal

process.permission.has('fs.read', 'index.js'); // true

process.permission.has('fs.read', 'custom-require.js'); // true

process.permission.has('fs.read', 'custom-require-2.js'); // true

.Ed

.It Fl -allow-fs-vfs

When using the Permission Model, a virtual file system cannot be

mounted by default: \fBvfs.mount()\fR throws \fBERR_INVALID_STATE\fR unless the

user explicitly passes the \fB--allow-fs-vfs\fR flag when starting Node.js.

A mounted VFS serves paths that the file system permissions do not describe,

so mounting one is gated on its own flag rather than on \fB--allow-fs-read\fR or

\fB--allow-fs-write\fR.

.Bd -literal

$ node --experimental-vfs --permission --allow-fs-vfs app.js

.Ed

.It Fl -allow-fs-write

This flag configures file system write permissions using

the Permission Model.

The valid arguments for the \fB--allow-fs-write\fR flag are:

.Bl -bullet

.It

\fB*\fR - To allow all \fBFileSystemWrite\fR operations.

.It

Multiple paths can be allowed using multiple \fB--allow-fs-write\fR flags.

Example \fB--allow-fs-write=/folder1/ --allow-fs-write=/folder2/\fR

.El

Paths delimited by comma (\fB,\fR) are no longer allowed.

When passing a single flag with a comma a warning will be displayed.

Examples can be found in the File System Permissions documentation.

.It Fl -allow-inspector

When using the Permission Model, the process will not be able to connect

through inspector protocol.

Attempts to do so will throw an \fBERR_ACCESS_DENIED\fR unless the

user explicitly passes the \fB--allow-inspector\fR flag when starting Node.js.

Example:

.Bd -literal

const { Session } = require('node:inspector/promises');

const session = new Session();

session.connect();

.Ed

.Bd -literal

$ node --permission index.js

Error: connect ERR_ACCESS_DENIED Access to this API has been restricted. Use --allow-inspector to manage permissions.

code: 'ERR_ACCESS_DENIED',

}

.Ed

.It Fl -allow-net

When using the Permission Model, the process will not be able to access

network by default.

Attempts to do so will throw an \fBERR_ACCESS_DENIED\fR unless the

user explicitly passes the \fB--allow-net\fR flag when starting Node.js.

Example:

.Bd -literal

const http = require('node:http');

// Attempt to bypass the permission

const req = http.get('http://example.com', () => {});

req.on('error', (err) => {

console.log('err', err);

});

.Ed

.Bd -literal

$ node --permission index.js

Error: connect ERR_ACCESS_DENIED Access to this API has been restricted. Use --allow-net to manage permissions.

code: 'ERR_ACCESS_DENIED',

}

.Ed

.It Fl -allow-openssl-store

When using the Permission Model, the process will not be able to use

OpenSSL STORE loaders by default, for example to load a private key from a

\fB{URL}\fR passed to \fBcrypto.createPrivateKey()\fR. Attempts to do so will throw

an \fBERR_ACCESS_DENIED\fR unless the user explicitly passes the

\fB--allow-openssl-store\fR flag. This permission can be dropped at runtime via

\fBpermission.drop()\fR.

This flag grants broad authority to configured OpenSSL STORE loaders. A loader

may access files, devices, tokens, or the network. Access performed by a loader

is not constrained by the \fBfs.read\fR, \fBfs.write\fR, or \fBnet\fR permission scopes.

Loaders and the modules they load are subject to \fB--allow-env\fR, however.

Environment variables they rely on, such as \fBSOFTHSM2_CONF\fR for SoftHSM, are

removed at startup unless they are granted explicitly with \fB--allow-env\fR. See

Environment variable permissions for details.

.It Fl -allow-wasi

When using the Permission Model, the process will not be capable of creating

any WASI instances by default.

For security reasons, the call will throw an \fBERR_ACCESS_DENIED\fR unless the

user explicitly passes the flag \fB--allow-wasi\fR in the main Node.js process.

Example:

.Bd -literal

const { WASI } = require('node:wasi');

// Attempt to bypass the permission

new WASI({

version: 'preview1',

// Attempt to mount the whole filesystem

preopens: {

'/': '/',

},

});

.Ed

.Bd -literal

$ node --permission --allow-fs-read=* index.js

Error: Access to this API has been restricted

at node:internal/main/run_main_module:30:49 {

code: 'ERR_ACCESS_DENIED',

permission: 'WASI',

}

.Ed

.It Fl -allow-worker

When using the Permission Model, the process will not be able to create any

worker threads by default.

For security reasons, the call will throw an \fBERR_ACCESS_DENIED\fR unless the

user explicitly pass the flag \fB--allow-worker\fR in the main Node.js process.

Example:

.Bd -literal

const { Worker } = require('node:worker_threads');

// Attempt to bypass the permission

new Worker(__filename);

.Ed

.Bd -literal

$ node --permission --allow-fs-read=* index.js

Error: Access to this API has been restricted

at node:internal/main/run_main_module:17:47 {

code: 'ERR_ACCESS_DENIED',

permission: 'WorkerThreads'

}

.Ed

.It Fl -bench

Starts the Node.js command-line benchmark runner. At least one explicit file or

glob pattern is required:

.Bd -literal

node --experimental-bench --bench benchmark.mjs

node --experimental-bench --bench 'benchmarks/**/*.js'

.Ed

The \fB--experimental-bench\fR flag is required to use this flag or any other

\fB--bench-*\fR option.

Quote glob patterns to prevent expansion by the shell. Matching files are

sorted and executed serially. By default, each file runs in a separate child

process. Benchmark files declare benchmarks using \fBnode:bench\fR; they must not

call \fBrun()\fR themselves. See the benchmark runner documentation for more

details.

This flag cannot be combined with \fB--test\fR, \fB--watch\fR, \fB--watch-path\fR,

\fB--check\fR, \fB--eval\fR, or \fB--interactive\fR.

.It Fl -bench-isolation Ns = Ns Ar mode

Configures benchmark file isolation. When \fBmode\fR is \fB'process'\fR, each matching

file runs in a separate child process. This is the default. Files are still run

serially so their measured work does not overlap.

When \fBmode\fR is \fB'none'\fR, all matching files and benchmarks run serially in the

benchmark runner process. This reduces startup overhead but allows module,

heap, and process state to carry between files. User writes to stdout or stderr

also share destinations with benchmark reporters in this mode.

The supported modes are \fB'process'\fR and \fB'none'\fR.

.It Fl -bench-name-pattern Ns = Ns Ar pattern

Only runs benchmarks whose full hierarchical name matches the JavaScript

regular expression \fBpattern\fR. Non-matching benchmarks are reported as skipped.

.It Fl -bench-reporter-destination Ns = Ns Ar destination

Specifies the destination for the corresponding benchmark reporter. The value

can be \fBstdout\fR, \fBstderr\fR, or a file path. A single reporter defaults to

\fBstdout\fR when no destination is specified.

.It Fl -bench-reporter Ns = Ns Ar reporter

Specifies a benchmark reporter. The built-in reporters are \fBspec\fR and \fBjson\fR.

The \fBjson\fR reporter emits newline-delimited JSON. A custom reporter can be

specified using a module specifier resolved from the current working directory.

This option can be repeated. When multiple reporters are specified, each must

have a corresponding \fB--bench-reporter-destination\fR. The default reporter is

\fBspec\fR.

.It Fl -bench-samples Ns = Ns Ar count

Overrides the maximum number of measured callback invocations for every

selected benchmark. A benchmark may finish earlier by calling

\fBcontext.done()\fR. \fBcount\fR must be an integer between \fB1\fR and \fB4294967295\fR.

.It Fl -bench-warmup Ns = Ns Ar count

Overrides the number of unreported warmup callback invocations for every

selected benchmark. \fBcount\fR must be an integer between \fB0\fR and \fB4294967295\fR.

.It Fl -build-sea Ns = Ns Ar config

Generates a single executable application from a JSON

configuration file. The argument must be a path to the configuration file. If

the path is not absolute, it is resolved relative to the current working

directory.

For configuration fields, cross-platform notes, and asset APIs, see

the single executable application documentation.

.It Fl -build-snapshot

Generates a snapshot blob when the process exits and writes it to

disk, which can be loaded later with \fB--snapshot-blob\fR.

When building the snapshot, if \fB--snapshot-blob\fR is not specified,

the generated blob will be written, by default, to \fBsnapshot.blob\fR

in the current working directory. Otherwise it will be written to

the path specified by \fB--snapshot-blob\fR.

.Bd -literal

$ 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.js

I am from the snapshot

.Ed

The \fBv8.startupSnapshot\fR API can be used to specify an entry point at

snapshot building time, thus avoiding the need of an additional entry

script at deserialization time:

.Bd -literal

$ 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.blob

I am from the snapshot

.Ed

For more information, check out the \fBv8.startupSnapshot\fR API documentation.

The snapshot currently only supports loading a single entrypoint during the

snapshot building process, which can load built-in modules, but not additional user-land modules.

Users can bundle their applications into a single script with their bundler

of choice before building a snapshot.

As it's complicated to ensure the serializablility of all built-in modules,

which are also growing over time, only a subset of the built-in modules are

well tested to be serializable during the snapshot building process.

The Node.js core test suite checks that a few fairly complex applications

can be snapshotted. The list of built-in modules being

captured by the built-in snapshot of Node.js is considered supported.

When the snapshot builder encounters a built-in module that cannot be

serialized, it may crash the snapshot building process. In that case a typical

workaround would be to delay loading that module until

runtime, using either \fBv8.startupSnapshot.setDeserializeMainFunction()\fR or

\fBv8.startupSnapshot.addDeserializeCallback()\fR. If serialization for

an additional module during the snapshot building process is needed,

please file a request in the Node.js issue tracker and link to it in the

tracking issue for user-land snapshots.

.It Fl -build-snapshot-config

Specifies the path to a JSON configuration file which configures snapshot

creation behavior.

The following options are currently supported:

.Bl -bullet

.It

\fBbuilder\fR \fB{string}\fR Required. Provides the name to the script that is executed

before building the snapshot, as if \fB--build-snapshot\fR had been passed

with \fBbuilder\fR as the main script name.

.It

\fBwithoutCodeCache\fR \fB{boolean}\fR Optional. Including the code cache reduces the

time spent on compiling functions included in the snapshot at the expense

of a bigger snapshot size and potentially breaking portability of the

snapshot.

.El

When using this flag, additional script files provided on the command line will

not be executed and instead be interpreted as regular command line arguments.

.It Fl c , Fl -check

Syntax check the script without executing.

.It Fl -completion-bash

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

.Bd -literal

node --completion-bash > node_bash_completion

source node_bash_completion

.Ed

.It Fl C Ar condition , Fl -conditions Ns = Ns Ar condition

Provide custom conditional exports resolution conditions.

Any number of custom string condition names are permitted.

The default Node.js conditions of \fB"node"\fR, \fB"default"\fR, \fB"import"\fR, and

\fB"require"\fR will always apply as defined.

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

.Bd -literal

node -C development app.js

.Ed

.It Fl -cpu-prof

Starts the V8 CPU profiler on start up, and writes the CPU profile to disk

before exit.

If \fB--cpu-prof-dir\fR is not specified, the generated profile is placed

in the current working directory.

If \fB--cpu-prof-name\fR is not specified, the generated profile is

named \fBCPU.${yyyymmdd}.${hhmmss}.${pid}.${tid}.${seq}.cpuprofile\fR.

.Bd -literal

$ node --cpu-prof index.js

$ ls *.cpuprofile

CPU.20190409.202950.15293.0.0.cpuprofile

.Ed

If \fB--cpu-prof-name\fR is specified, the provided value is used as a template

for the file name. The following placeholder is supported and will be

substituted at runtime:

.Bl -bullet

.It

\fB${pid}\fR — the current process ID

.El

.Bd -literal

$ node --cpu-prof --cpu-prof-name 'CPU.${pid}.cpuprofile' index.js

$ ls *.cpuprofile

CPU.15293.cpuprofile

.Ed

.It Fl -cpu-prof-dir

Specify the directory where the CPU profiles generated by \fB--cpu-prof\fR will

be placed.

The default value is controlled by the

\fB--diagnostic-dir\fR command-line option.

.It Fl -cpu-prof-interval

Specify the sampling interval in microseconds for the CPU profiles generated

by \fB--cpu-prof\fR. The default is 1000 microseconds.

.It Fl -cpu-prof-name

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

.It Fl -diagnostic-dir Ns = Ns Ar directory

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

Defaults to current working directory.

Affects the default output directory of:

.Bl -bullet

.It

.It

.It

.El

.It Fl -disable-proto Ns = Ns Ar mode

Disable the \fBObject.prototype.__proto__\fR property. If \fBmode\fR is \fBdelete\fR, the

property is removed entirely. If \fBmode\fR is \fBthrow\fR, accesses to the

property throw an exception with the code \fBERR_PROTO_ACCESS\fR.

.It Fl -disable-sigusr1

Disable the ability of starting a debugging session by sending a

\fBSIGUSR1\fR signal to the process.

.It Fl -disable-warning Ns = Ns Ar code-or-type

Disable specific process warnings by \fBcode\fR or \fBtype\fR.

Warnings emitted from \fBprocess.emitWarning()\fR may contain a

\fBcode\fR and a \fBtype\fR. This option will not-emit warnings that have a matching

\fBcode\fR or \fBtype\fR.

List of deprecation warnings.

The Node.js core warning types are: \fBDeprecationWarning\fR and

For example, the following script will not emit

DEP0025 \fBrequire('node:sys')\fR when executed with

\fBnode --disable-warning=DEP0025\fR:

.Bd -literal

import sys from 'node:sys';

.Ed

.Bd -literal

const sys = require('node:sys');

.Ed

For example, the following script will emit the

DEP0025 \fBrequire('node:sys')\fR, but not any Experimental

Warnings (such as

ExperimentalWarning: \fBvm.measureMemory\fR is an experimental feature

in <=v21) when executed with \fBnode --disable-warning=ExperimentalWarning\fR:

.Bd -literal

import sys from 'node:sys';

import vm from 'node:vm';

vm.measureMemory();

.Ed

.Bd -literal

const sys = require('node:sys');

const vm = require('node:vm');

vm.measureMemory();

.Ed

.It Fl -disable-wasm-trap-handler

Node.js enables V8's trap-handler-based WebAssembly bound checks on 64-bit platforms,

which significantly improves WebAssembly performance by eliminating the need for

inline bound checks. This optimization requires allocating a large virtual memory

cage per WebAssembly memory instance (currently typically 8GB for 32-bit WebAssembly memory,

16GB for 64-bit WebAssembly memory) to trap out-of-bound accesses. On most 64-bit

platforms, the virtual memory address space is usually large enough (around 128TB)

to accommodate typical WebAssembly usages, but if the machine has manual limits

on virtual memory (e.g. through \fBulimit -v\fR), WebAssembly memory allocation is

more likely to fail with \fBWebAssembly.Memory(): could not allocate memory\fR.

At startup, Node.js automatically checks whether there is enough virtual memory

available to allocate at least one cage, and if not, the trap-handler optimization

is automatically disabled so that WebAssembly can still run using inline

bound checks (with less optimal performance). But if the application needs to create

many WebAssembly memory instances and the machine still configures a relatively high

limit on virtual memory, allocation of WebAssembly memory instances may still fail

more quickly than expected due to the raised virtual memory usage.

\fB--disable-wasm-trap-handler\fR fully disables this optimization so that WebAssembly memory

instances always use inline bound checks instead of reserving large virtual memory cages.

This allows more instances to be created when the virtual memory address space available

to the Node.js process is limited.

.It Fl -disallow-code-generation-from-strings

Make built-in language features like \fBeval\fR and \fBnew Function\fR that generate

code from strings throw an exception instead. This does not affect the Node.js

\fBnode:vm\fR module.

.It Fl -dns-result-order Ns = Ns Ar order

Set the default value of \fBorder\fR in \fBdns.lookup()\fR and

\fBdnsPromises.lookup()\fR. The value could be:

.Bl -bullet

.It

\fBipv4first\fR: sets default \fBorder\fR to \fBipv4first\fR.

.It

\fBipv6first\fR: sets default \fBorder\fR to \fBipv6first\fR.

.It

\fBverbatim\fR: sets default \fBorder\fR to \fBverbatim\fR.

.El

The default is \fBverbatim\fR and \fBdns.setDefaultResultOrder()\fR have higher

priority than \fB--dns-result-order\fR.

.It Fl -enable-fips

Enable FIPS mode at startup. With OpenSSL 3, a configured provider named

\fBfips\fR must be available and initialize successfully. With OpenSSL 1.1.1,

Node.js must be built against a FIPS-capable OpenSSL.

.It Fl -enable-fips-indicator-events

Publish OpenSSL FIPS indicator results to the

\fB'crypto.fips.indicator'\fR diagnostics channel. This option requires OpenSSL

3.4 or later. It does not enable FIPS mode or change whether an operation

is permitted.

.It Fl -enable-source-maps

Enable Source Map support for stack traces.

When using a transpiler, such as TypeScript, stack traces thrown by an

application reference the transpiled code, not the original source position.

\fB--enable-source-maps\fR enables caching of Source Maps and makes a best

effort to report stack traces relative to the original source file.

Overriding \fBError.prepareStackTrace\fR may prevent \fB--enable-source-maps\fR from

modifying the stack trace. Call and return the results of the original

\fBError.prepareStackTrace\fR in the overriding function to modify the stack trace

with source maps.

.Bd -literal

const originalPrepareStackTrace = Error.prepareStackTrace;

Error.prepareStackTrace = (error, trace) => {

// Modify error and trace and format stack trace with

// original Error.prepareStackTrace.

return originalPrepareStackTrace(error, trace);

};

.Ed

Note, enabling source maps can introduce latency to your application

when \fBError.stack\fR is accessed. If you access \fBError.stack\fR frequently

in your application, take into account the performance implications

of \fB--enable-source-maps\fR.

.It Fl -entry-url

When present, Node.js will interpret the entry point as a URL, rather than a

path.

Follows ECMAScript module resolution rules.

Any query parameter or hash in the URL will be accessible via \fBimport.meta.url\fR.

.Bd -literal

node --entry-url 'file:///path/to/file.js?queryparams=work#and-hashes-too'

node --entry-url 'file.ts?query#hash'

node --entry-url 'data:text/javascript,console.log("Hello")'

.Ed

.It Fl -env-file-if-exists Ns = Ns Ar file

Behavior is the same as \fB--env-file\fR, but an error is not thrown if the file

does not exist.

.It Fl -env-file Ns = Ns Ar file

Loads environment variables from a file relative to the current directory,

making them available to applications on \fBprocess.env\fR. The environment

variables which configure Node.js, such as \fBNODE_OPTIONS\fR,

are parsed and applied. If the same variable is defined in the environment and

in the file, the value from the environment takes precedence.

You can pass multiple \fB--env-file\fR arguments. Subsequent files override

pre-existing variables defined in previous files.

An error is thrown if the file does not exist.

.Bd -literal

node --env-file=.env --env-file=.development.env index.js

.Ed

The format of the file should be one line per key-value pair of environment

variable name and value separated by \fB=\fR:

.Bd -literal

PORT=3000

.Ed

Any text after a \fB#\fR is treated as a comment:

.Bd -literal

# This is a comment

PORT=3000 # This is also a comment

.Ed

Values can start and end with the following quotes: \fB`\fR, \fB"\fR or \fB'\fR.

They are omitted from the values.

.Bd -literal

USERNAME="nodejs" # will result in `nodejs` as the value.

.Ed

Multi-line values are supported:

.Bd -literal

MULTI_LINE="THIS IS

A MULTILINE"

# will result in `THIS IS\\nA MULTILINE` as the value.

.Ed

Export keyword before a key is ignored:

.Bd -literal

export USERNAME="nodejs" # will result in `nodejs` as the value.

.Ed

If you want to load environment variables from a file that may not exist, you

can use the \fB--env-file-if-exists\fR flag instead.

.It Fl e , Fl -eval Ar "script"

Evaluate the following argument as JavaScript. The modules which are

predefined in the REPL can also be used in \fBscript\fR.

If \fBscript\fR starts with \fB-\fR, pass it using \fB=\fR (for example,

\fBnode --print --eval=-42\fR) so it is parsed as the value of \fB--eval\fR.

On Windows, using \fBcmd.exe\fR a single quote will not work correctly because it

only recognizes double \fB"\fR for quoting. In Powershell or Git bash, both \fB'\fR

and \fB"\fR are usable.

It is possible to run code containing inline types unless the

\fB--no-strip-types\fR flag is provided.

.It Fl -experimental-addon-modules

Enable experimental import support for \fB.node\fR addons.

.It Fl -experimental-bench

Enable the experimental \fBnode:bench\fR module and command-line benchmark runner.

.It Fl -experimental-config-file Ns = Ns Ar path , Fl -experimental-config-file

If present, Node.js will look for a configuration file at the specified path.

If the path is not specified, Node.js will look for a \fBnode.config.json\fR file

in the current working directory.

To specify a custom path, use the \fB--experimental-config-file=path\fR form.

The space-separated \fB--experimental-config-file path\fR form is not supported.

The alias \fB--experimental-default-config-file\fR is equivalent to

\fB--experimental-config-file\fR without an argument.

Node.js will read the configuration file and apply the settings. The

configuration file should be a JSON file with the following structure. \fBvX.Y.Z\fR

in the \fB$schema\fR must be replaced with the version of Node.js you are using or

\fBlatest-vX.x\fR for the latest version of that major release line.

.Bd -literal

{

"$schema": "https://nodejs.org/dist/vX.Y.Z/docs/node-config-schema.json",

"nodeOptions": {

"import": [

"amaro/strip"

],

"watch-path": "src",

"watch-preserve-output": true

},

"test": {

"test-isolation": "process"

},

"watch": {

"watch-preserve-output": true

}

}

.Ed

The configuration file supports namespace-specific options:

.Bl -bullet

.It

The \fBnodeOptions\fR field contains CLI flags that are allowed in \fBNODE_OPTIONS\fR.

.It

Namespace fields like \fBtest\fR, \fBwatch\fR, and \fBpermission\fR contain configuration specific to that subsystem.

.El

The configuration file can target a specific Node.js major version with

\fBnodeVersion\fR:

.Bd -literal

{

"nodeVersion": 25,

"nodeOptions": {

"watch-path": "src"

}

}

.Ed

To keep multiple version-specific configurations in the same file, use the

\fBconfigs\fR array. Node.js will use the first entry whose \fBnodeVersion\fR matches

the current Node.js major version:

.Bd -literal

{

"$schema": "https://nodejs.org/dist/latest-v26.x/docs/node-config-schema.json",

"configs": [

{

"nodeVersion": 25,

"config": {

"$schema": "https://nodejs.org/dist/latest-v25.x/docs/node-config-schema.json",

"nodeOptions": {

"watch-path": "src"

}

}

}

]

}

.Ed

When \fBconfigs\fR is used, the top level may only contain \fB$schema\fR and

\fBconfigs\fR. Each \fBconfigs\fR item must define an integer \fBnodeVersion\fR and an

object \fBconfig\fR. A single top-level config does not require \fBnodeVersion\fR, but

if present it must match the current Node.js major version.

When a namespace is present in the

configuration file, Node.js automatically enables the corresponding flag

(e.g., \fB--test\fR, \fB--watch\fR, \fB--permission\fR). This allows you to configure

subsystem-specific options without explicitly passing the flag on the command line.

For example:

.Bd -literal

{

"test": {

"test-isolation": "process"

}

}

.Ed

is equivalent to:

.Bd -literal

node --test --test-isolation=process

.Ed

To disable the automatic flag while still using namespace options, you can

explicitly set the flag to \fBfalse\fR within the namespace:

.Bd -literal

{

"test": {

"test": false,

"test-isolation": "process"

}

}

.Ed

No-op flags are not supported.

Not all V8 flags are currently supported.

It is possible to use the official JSON schema

to validate the configuration file, which may vary depending on the Node.js version.

Each key in the configuration file corresponds to a flag that can be passed

as a command-line argument. The value of the key is the value that would be

passed to the flag.

For example, the configuration file above is equivalent to

the following command-line arguments:

.Bd -literal

node --import amaro/strip --watch-path=src --watch-preserve-output --test-isolation=process

.Ed

The priority in configuration is as follows:

.Bl -bullet

.It

NODE_OPTIONS and command-line options

.It

Dotenv NODE_OPTIONS

.It

Configuration file

.El

Values in the configuration file will not override the values in the environment

variables, command-line options, or the \fBNODE_OPTIONS\fR env file parsed by the

\fB--env-file\fR flag.

Keys cannot be duplicated within the same or different namespaces.

The configuration parser will throw an error if the configuration file contains

unknown keys or keys that cannot be used in a namespace.

Node.js will not sanitize or perform validation on the user-provided configuration,

so \fBNEVER\fR use untrusted configuration files.

.It Fl -experimental-default-config-file

This flag is an alias for \fB--experimental-config-file\fR without an argument.

If present, Node.js will look for a

\fBnode.config.json\fR file in the current working directory and load it as a

configuration file.

.It Fl -experimental-dtls

Enable experimental support for the DTLS protocol. See the

dtls documentation for details.

.It Fl -experimental-eventsource

Enable exposition of EventSource Web API on the global scope.

.It Fl -experimental-import-meta-resolve

Enable experimental \fBimport.meta.resolve()\fR parent URL support, which allows

passing a second \fBparentURL\fR argument for contextual resolution.

Previously gated the entire \fBimport.meta.resolve\fR feature.

.It Fl -experimental-import-text

Enable experimental support for importing modules with

\fBwith { type: 'text' }\fR.

.It Fl -experimental-inspector-network-resource

Enable experimental support for inspector network resources.

.It Fl -experimental-loader Ns = Ns Ar module

Specify the \fBmodule\fR containing exported asynchronous module customization hooks.

\fBmodule\fR may be any string accepted as an \fBimport\fR specifier.

This feature requires \fB--allow-worker\fR if used with the Permission Model.

.It Fl -experimental-network-inspection

Enable experimental support for the network inspection with Chrome DevTools.

.It Fl -experimental-package-map Ns = Ns Ar <path>

Enable experimental package map resolution. The \fBpath\fR argument specifies the

location of a JSON configuration file that defines package resolution mappings.

.Bd -literal

node --experimental-package-map=./package-map.json app.js

.Ed

When enabled, bare specifier resolution consults the package map for resolution.

This allows explicit control over which packages can import which dependencies.

See Package maps for details on the configuration file format and

resolution algorithm.

.It Fl -experimental-print-required-tla

If the ES module graph cannot be \fBrequire()\fR'd because it contains any top-level \fBawait\fR,

this flag allows Node.js to locate and print their locations.

.It Fl -experimental-quic

Enable experimental support for the QUIC protocol.

.It Fl -experimental-sea-config

Use this flag to generate a blob that can be injected into the Node.js

binary to produce a single executable application. See the documentation

about this configuration for details.

.It Fl -experimental-shadow-realm

Use this flag to enable ShadowRealm support.

.It Fl -experimental-storage-inspection

Enable experimental support for storage inspection

.It Fl -experimental-stream-iter

Enable the experimental \fBnode:stream/iter\fR module.

.It Fl -experimental-test-coverage

When used in conjunction with the \fBnode:test\fR module, a code coverage report is

generated as part of the test runner output. If no tests are run, a coverage

report is not generated. See the documentation on

collecting code coverage from tests for more details.

.It Fl -experimental-test-module-mocks

Enable module mocking in the test runner.

This feature requires \fB--allow-worker\fR if used with the Permission Model.

.It Fl -experimental-test-tag-filter Ns = Ns Ar '<expr>'

Run only tests that match the provided boolean tag-filter expression. Tests

declare tags via the \fBtags\fR option on \fBtest()\fR, \fBit()\fR, \fBsuite()\fR, or

\fBdescribe()\fR. Tags inherit from suites to nested tests by union.

The expression supports boolean operators (\fBand\fR/\fB&&\fR, \fBor\fR/\fB||\fR,

\fBnot\fR/\fB!\fR), parentheses for grouping, and \fB*\fR wildcards inside identifiers.

Standard precedence applies: \fBnot\fR binds tighter than \fBand\fR, which binds

tighter than \fBor\fR. See Test tags for the full grammar and behavior.

The flag may be specified more than once; multiple expressions are combined

with AND, so a test must satisfy every expression to run.

A malformed expression causes the test runner to exit with a non-zero status

before running any tests.

.It Fl -experimental-vfs

Enable the experimental \fBnode:vfs\fR module.

.It Fl -experimental-vm-modules

Enable experimental ES Module support in the \fBnode:vm\fR module.

.It Fl -experimental-wasi-unstable-preview1

Enable experimental WebAssembly System Interface (WASI) support.

.It Fl -experimental-web-worker

Enable experimental support for the Web Worker API.

.It Fl -experimental-worker-inspection

Enable experimental support for the worker inspection with Chrome DevTools.

.It Fl -force-context-aware

Disable loading native addons that are not context-aware.

.It Fl -force-fips Ns = Ns Ar [mode]

Enable FIPS mode at startup and prevent it from being disabled from script

code. The same OpenSSL requirements as \fB--enable-fips\fR apply.

An optional mode can be specified using \fB--force-fips=mode\fR:

.Bl -bullet

.It

\fBprovider\fR: Preserve the OpenSSL FIPS provider's configured handling of

non-approved operations. This is the current default when the mode is

omitted.

.It

\fBstrict\fR: Reject non-approved operations reported through the OpenSSL FIPS

indicator callback. This mode requires OpenSSL 3.4 or later.

.El

The \fBstrict\fR mode only covers operations reported through the callback for

OpenSSL's default library context. It does not cover native addons that use

another \fBOSSL_LIB_CTX\fR or another copy of \fBlibcrypto\fR, nor operation-specific

indicators that do not invoke the callback.

.It Fl -force-node-api-uncaught-exceptions-policy

Enforces \fBuncaughtException\fR event on Node-API asynchronous callbacks.

To prevent from an existing add-on from crashing the process, this flag is not

enabled by default. In the future, this flag will be enabled by default to

enforce the correct behavior.

.It Fl -frozen-intrinsics

Enable experimental frozen intrinsics like \fBArray\fR and \fBObject\fR.

Only the root context is supported. There is no guarantee that

\fBglobalThis.Array\fR is indeed the default intrinsic reference. Code may break

under this flag.

To allow polyfills to be added,

\fB--require\fR and \fB--import\fR both run before freezing intrinsics.

.It Fl -heap-prof

Starts the V8 heap profiler on start up, and writes the heap profile to disk

before exit.

If \fB--heap-prof-dir\fR is not specified, the generated profile is placed

in the current working directory.

If \fB--heap-prof-name\fR is not specified, the generated profile is

named \fBHeap.${yyyymmdd}.${hhmmss}.${pid}.${tid}.${seq}.heapprofile\fR.

.Bd -literal

$ node --heap-prof index.js

$ ls *.heapprofile

Heap.20190409.202950.15293.0.001.heapprofile

.Ed