Node.js v24.11.1 documentation

ECMAScript modules loader entry point caveat#

When loading, the ES module loader loads the program entry point, the node command will accept as input only files with .js, .mjs, or .cjs extensions. With the following flags, additional file extensions are enabled:

• --experimental-addon-modules for files with .node extension.

-#

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 options are 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, then the 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-mortem analysis using a debugger (such as lldb, gdb, and mdb).

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

--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 ERR_DLOPEN_DISABLED unless the user explicitly passes the --allow-addons flag when starting Node.js.

Example:

// Attempt to require an native addon
require('nodejs-addon-example'); copy

$ 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'
} copy

--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 ERR_ACCESS_DENIED unless the user explicitly passes the --allow-child-process flag when starting Node.js.

Example:

const childProcess = require('node:child_process');
// Attempt to bypass the permission
childProcess.spawn('node', ['-e', 'require("fs").writeFileSync("/new-file", "example")']); copy

$ 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'
} copy

The child_process.fork() API inherits the execution arguments from the parent process. This means that if Node.js is started with the Permission Model enabled and the --allow-child-process flag is set, any child process created using child_process.fork() will automatically receive all relevant Permission Model flags.

This behavior also applies to child_process.spawn(), but in that case, the flags are propagated via the NODE_OPTIONS environment variable rather than directly through the process arguments.

--allow-fs-read#

This flag configures file system read permissions using the Permission Model.

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

• * - To allow all FileSystemRead operations.
• Multiple paths can be allowed using multiple --allow-fs-read flags. Example --allow-fs-read=/folder1/ --allow-fs-read=/folder1/

Examples can be found in the File System Permissions documentation.

The initializer module and custom --require modules has a implicit read permission.

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

• The custom-require.js, custom-require-2.js, and index.js will be by default in the allowed read list.

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

--allow-fs-write#

This flag configures file system write permissions using the Permission Model.

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

• * - To allow all FileSystemWrite operations.
• Multiple paths can be allowed using multiple --allow-fs-write flags. Example --allow-fs-write=/folder1/ --allow-fs-write=/folder1/

Paths delimited by comma (,) 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.

--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 ERR_ACCESS_DENIED unless the user explicitly passes the flag --allow-wasi in the main Node.js process.

Example:

const { WASI } = require('node:wasi');
// Attempt to bypass the permission
new WASI({
  version: 'preview1',
  // Attempt to mount the whole filesystem
  preopens: {
    '/': '/',
  },
}); copy

$ 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',
} copy

--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 ERR_ACCESS_DENIED unless the user explicitly pass the flag --allow-worker in the main Node.js process.

Example:

const { Worker } = require('node:worker_threads');
// Attempt to bypass the permission
new Worker(__filename); copy

$ 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'
} copy

--build-snapshot#

Generates a snapshot blob when the process exits and writes it to disk, 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, to snapshot.blob in the current working directory. Otherwise it will be written to the 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.js
I am from the snapshot copy

The v8.startupSnapshot 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:

$ 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 copy

For more information, check out the v8.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 only one single file can be snapshotted. Users can bundle their applications into a single script with their bundler of choice before building a snapshot, however.
2. Only a subset of the built-in modules work in the snapshot, though the Node.js core test suite checks that a few fairly complex applications can be snapshotted. Support for more modules are being added. If any crashes or buggy behaviors occur when building a snapshot, please file a report in the Node.js issue tracker and link to it in the tracking issue for user-land snapshots.

--build-snapshot-config#

Specifies the path to a JSON configuration file which configures snapshot creation behavior.

The following options are currently supported:

• builder <string> Required. Provides the name to the script that is executed before building the snapshot, as if --build-snapshot had been passed with builder as the main script name.
• withoutCodeCache <boolean> 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.

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.

-c, --check#

Syntax check the script without executing.

--completion-bash#

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

node --completion-bash > node_bash_completion
source node_bash_completion copy

-C condition, --conditions=condition#

Provide custom conditional exports resolution conditions.

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

--cpu-prof#

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

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

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

$ node --cpu-prof index.js
$ ls *.cpuprofile
CPU.20190409.202950.15293.0.0.cpuprofile copy

If --cpu-prof-name 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:

• ${pid} — the current process ID

$ node --cpu-prof --cpu-prof-name 'CPU.${pid}.cpuprofile' index.js
$ ls *.cpuprofile
CPU.15293.cpuprofile copy

--cpu-prof-dir#

Specify the directory where the CPU profiles generated by --cpu-prof will be 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 generated by --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 the Object.prototype.__proto__ property. If mode is delete, the property is removed entirely. If mode is throw, accesses to the property throw an exception with the code ERR_PROTO_ACCESS.

--disable-sigusr1#

Disable the ability of starting a debugging session by sending a SIGUSR1 signal to the process.

--disable-warning=code-or-type#

Disable specific process warnings by code or type.

Warnings emitted from process.emitWarning() may contain a code and a type. This option will not-emit warnings that have a matching code or type.

List of deprecation warnings.

The Node.js core warning types are: DeprecationWarning and ExperimentalWarning

For example, the following script will not emit DEP0025 require('node:sys') when executed with node --disable-warning=DEP0025:

import sys from 'node:sys';const sys = require('node:sys');copy

For example, the following script will emit the DEP0025 require('node:sys'), but not any Experimental Warnings (such as ExperimentalWarning: vm.measureMemory is an experimental feature in <=v21) when executed with node --disable-warning=ExperimentalWarning:

import sys from 'node:sys';
import vm from 'node:vm';

vm.measureMemory();const sys = require('node:sys');
const vm = require('node:vm');

vm.measureMemory();copy

--disable-wasm-trap-handler#

By default, Node.js enables trap-handler-based WebAssembly bound checks. As a result, V8 does not need to insert inline bound checks int the code compiled from WebAssembly which may speedup WebAssembly execution significantly, but this optimization requires allocating a big virtual memory cage (currently 10GB). If the Node.js process does not have access to a large enough virtual memory address space due to system configurations or hardware limitations, users won't be able to run any WebAssembly that involves allocation in this virtual memory cage and will see an out-of-memory error.

$ ulimit -v 5000000
$ node -p "new WebAssembly.Memory({ initial: 10, maximum: 100 });"
[eval]:1
new WebAssembly.Memory({ initial: 10, maximum: 100 });
^

RangeError: WebAssembly.Memory(): could not allocate memory
    at [eval]:1:1
    at runScriptInThisContext (node:internal/vm:209:10)
    at node:internal/process/execution:118:14
    at [eval]-wrapper:6:24
    at runScript (node:internal/process/execution:101:62)
    at evalScript (node:internal/process/execution:136:3)
    at node:internal/main/eval_string:49:3
 copy

--disable-wasm-trap-handler disables this optimization so that users can at least run WebAssembly (with less optimal performance) when the virtual memory address space available to their Node.js process is lower than what the V8 WebAssembly memory cage needs.

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

Make built-in language features like eval and new Function that generate code from strings throw an exception instead. This does not affect the Node.js node:vm module.

--dns-result-order=order#

Set the default value of order in dns.lookup() and dnsPromises.lookup(). The value could be:

• ipv4first: sets default order to ipv4first.
• ipv6first: sets default order to ipv6first.
• verbatim: sets default order to verbatim.

The default is verbatim and dns.setDefaultResultOrder() have higher priority than --dns-result-order.

--enable-fips#

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

--enable-network-family-autoselection#

Enables the family autoselection algorithm unless connection options explicitly disables it.

--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. --enable-source-maps enables caching of Source Maps and makes a best effort to report stack traces relative to the original source file.

Overriding Error.prepareStackTrace may prevent --enable-source-maps from modifying the stack trace. Call and return the results of the original Error.prepareStackTrace in the overriding function to modify the stack trace with source maps.

const originalPrepareStackTrace = Error.prepareStackTrace;
Error.prepareStackTrace = (error, trace) => {
  // Modify error and trace and format stack trace with
  // original Error.prepareStackTrace.
  return originalPrepareStackTrace(error, trace);
}; copy

Note, enabling source maps can introduce latency to your application when Error.stack is accessed. If you access Error.stack frequently in your application, take into account the performance implications of --enable-source-maps.

--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 import.meta.url.

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")' copy

--env-file-if-exists=file#

Behavior is the same as --env-file, but an error is not thrown if the file does not exist.

--env-file=file#

Loads environment variables from a file relative to the current directory, making them available to applications on process.env. The environment variables which configure Node.js, such as NODE_OPTIONS, 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 --env-file arguments. Subsequent files override pre-existing variables defined in previous files.

An error is thrown if the file does not exist.

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

The format of the file should be one line per key-value pair of environment variable name and value separated by =:

PORT=3000 copy

Any text after a # is treated as a comment:

# This is a comment
PORT=3000 # This is also a comment copy

Values can start and end with the following quotes: `, " or '. They are omitted from the values.

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

Multi-line values are supported:

MULTI_LINE="THIS IS
A MULTILINE"
# will result in `THIS IS\nA MULTILINE` as the value. copy

Export keyword before a key is ignored:

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

If you want to load environment variables from a file that may not exist, you can use the --env-file-if-exists flag instead.

-e, --eval "script"#

Evaluate the following argument as JavaScript. The modules which are predefined in the REPL can also be used in script.

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

It is possible to run code containing inline types unless the --no-experimental-strip-types flag is provided.

--experimental-addon-modules#

Enable experimental import support for .node addons.

--experimental-config-file=config#

If present, Node.js will look for a configuration file at the specified path. Node.js will read the configuration file and apply the settings. The configuration file should be a JSON file with the following structure. vX.Y.Z in the $schema must be replaced with the version of Node.js you are using.

{
  "$schema": "https://nodejs.org/dist/vX.Y.Z/docs/node-config-schema.json",
  "nodeOptions": {
    "import": [
      "amaro/strip"
    ],
    "watch-path": "src",
    "watch-preserve-output": true
  },
  "testRunner": {
    "test-isolation": "process"
  }
} copy

The configuration file supports namespace-specific options:

• The nodeOptions field contains CLI flags that are allowed in NODE_OPTIONS.

• Namespace fields like testRunner contain configuration specific to that subsystem.

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:

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

The priority in configuration is as follows:

1. NODE_OPTIONS and command-line options
2. Configuration file
3. Dotenv NODE_OPTIONS

Values in the configuration file will not override the values in the environment variables and command-line options, but will override the values in the NODE_OPTIONS env file parsed by the --env-file 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 NEVER use untrusted configuration files.

--experimental-default-config-file#

If the --experimental-default-config-file flag is present, Node.js will look for a node.config.json file in the current working directory and load it as a as configuration file.

--experimental-eventsource#

Enable exposition of EventSource Web API on the global scope.

--experimental-import-meta-resolve#

Enable experimental import.meta.resolve() parent URL support, which allows passing a second parentURL argument for contextual resolution.

Previously gated the entire import.meta.resolve feature.

--experimental-inspector-network-resource#

Enable experimental support for inspector network resources.

--experimental-loader=module#

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

Specify the module containing exported module customization hooks. module may be any string accepted as an import specifier.

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

--experimental-network-inspection#

Enable experimental support for the network inspection with Chrome DevTools.

--experimental-print-required-tla#

If the ES module being require()'d contains top-level await, this flag allows Node.js to evaluate the module, try to locate the top-level awaits, and print their location to help users find them.

--experimental-require-module#

Supports loading a synchronous ES module graph in require().

See Loading ECMAScript modules using require().

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

--experimental-shadow-realm#

Use this flag to enable ShadowRealm support.

--experimental-test-coverage#

When used in conjunction with the node:test 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.

--experimental-test-module-mocks#

Enable module mocking in the test runner.

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

--experimental-transform-types#

Enables the transformation of TypeScript-only syntax into JavaScript code. Implies --enable-source-maps.

--experimental-vm-modules#

Enable experimental ES Module support in the node:vm module.

--experimental-wasi-unstable-preview1#

Enable experimental WebAssembly System Interface (WASI) support.

--experimental-webstorage#

Enable experimental Web Storage support.

--experimental-worker-inspection#

Enable experimental support for the worker inspection with Chrome DevTools.

--expose-gc#

This flag will expose the gc extension from V8.

if (globalThis.gc) {
  globalThis.gc();
} copy

--force-context-aware#

Disable loading native addons that are not context-aware.

--force-fips#

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

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