Process events#

Theprocess object is an instance ofEventEmitter.

import processfrom'node:process';process.on('beforeExit',(code) => {console.log('Process beforeExit event with code: ', code);});process.on('exit',(code) => {console.log('Process exit event with code: ', code);});console.log('This message is displayed first.');// Prints:// This message is displayed first.// Process beforeExit event with code: 0// Process exit event with code: 0const process =require('node:process');process.on('beforeExit',(code) => {console.log('Process beforeExit event with code: ', code);});process.on('exit',(code) => {console.log('Process exit event with code: ', code);});console.log('This message is displayed first.');// Prints:// This message is displayed first.// Process beforeExit event with code: 0// Process exit event with code: 0copy

import processfrom'node:process';process.on('exit',(code) => {console.log(`About to exit with code:${code}`);});const process =require('node:process');process.on('exit',(code) => {console.log(`About to exit with code:${code}`);});copy

import processfrom'node:process';process.on('exit',(code) => {setTimeout(() => {console.log('This will not run');  },0);});const process =require('node:process');process.on('exit',(code) => {setTimeout(() => {console.log('This will not run');  },0);});copy

import processfrom'node:process';process.on('multipleResolves',(type, promise, reason) => {console.error(type, promise, reason);setImmediate(() => process.exit(1));});asyncfunctionmain() {try {returnawaitnewPromise((resolve, reject) => {resolve('First call');resolve('Swallowed resolve');reject(newError('Swallowed reject'));    });  }catch {thrownewError('Failed');  }}main().then(console.log);// resolve: Promise { 'First call' } 'Swallowed resolve'// reject: Promise { 'First call' } Error: Swallowed reject//     at Promise (*)//     at new Promise (<anonymous>)//     at main (*)// First callconst process =require('node:process');process.on('multipleResolves',(type, promise, reason) => {console.error(type, promise, reason);setImmediate(() => process.exit(1));});asyncfunctionmain() {try {returnawaitnewPromise((resolve, reject) => {resolve('First call');resolve('Swallowed resolve');reject(newError('Swallowed reject'));    });  }catch {thrownewError('Failed');  }}main().then(console.log);// resolve: Promise { 'First call' } 'Swallowed resolve'// reject: Promise { 'First call' } Error: Swallowed reject//     at Promise (*)//     at new Promise (<anonymous>)//     at main (*)// First callcopy

import processfrom'node:process';const unhandledRejections =newMap();process.on('unhandledRejection',(reason, promise) => {  unhandledRejections.set(promise, reason);});process.on('rejectionHandled',(promise) => {  unhandledRejections.delete(promise);});const process =require('node:process');const unhandledRejections =newMap();process.on('unhandledRejection',(reason, promise) => {  unhandledRejections.set(promise, reason);});process.on('rejectionHandled',(promise) => {  unhandledRejections.delete(promise);});copy

import processfrom'node:process';import fsfrom'node:fs';process.on('uncaughtException',(err, origin) => {  fs.writeSync(    process.stderr.fd,`Caught exception:${err}\n` +`Exception origin:${origin}\n`,  );});setTimeout(() => {console.log('This will still run.');},500);// Intentionally cause an exception, but don't catch it.nonexistentFunc();console.log('This will not run.');const process =require('node:process');const fs =require('node:fs');process.on('uncaughtException',(err, origin) => {  fs.writeSync(    process.stderr.fd,`Caught exception:${err}\n` +`Exception origin:${origin}\n`,  );});setTimeout(() => {console.log('This will still run.');},500);// Intentionally cause an exception, but don't catch it.nonexistentFunc();console.log('This will not run.');copy

import processfrom'node:process';process.on('uncaughtExceptionMonitor',(err, origin) => {MyMonitoringTool.logSync(err, origin);});// Intentionally cause an exception, but don't catch it.nonexistentFunc();// Still crashes Node.jsconst process =require('node:process');process.on('uncaughtExceptionMonitor',(err, origin) => {MyMonitoringTool.logSync(err, origin);});// Intentionally cause an exception, but don't catch it.nonexistentFunc();// Still crashes Node.jscopy

import processfrom'node:process';process.on('unhandledRejection',(reason, promise) => {console.log('Unhandled Rejection at:', promise,'reason:', reason);// Application specific logging, throwing an error, or other logic here});somePromise.then((res) => {returnreportToUser(JSON.pasre(res));// Note the typo (`pasre`)});// No `.catch()` or `.then()`const process =require('node:process');process.on('unhandledRejection',(reason, promise) => {console.log('Unhandled Rejection at:', promise,'reason:', reason);// Application specific logging, throwing an error, or other logic here});somePromise.then((res) => {returnreportToUser(JSON.pasre(res));// Note the typo (`pasre`)});// No `.catch()` or `.then()`copy

import processfrom'node:process';functionSomeResource() {// Initially set the loaded status to a rejected promisethis.loaded =Promise.reject(newError('Resource not yet loaded!'));}const resource =newSomeResource();// no .catch or .then on resource.loaded for at least a turnconst process =require('node:process');functionSomeResource() {// Initially set the loaded status to a rejected promisethis.loaded =Promise.reject(newError('Resource not yet loaded!'));}const resource =newSomeResource();// no .catch or .then on resource.loaded for at least a turncopy

import processfrom'node:process';process.on('warning',(warning) => {console.warn(warning.name);// Print the warning nameconsole.warn(warning.message);// Print the warning messageconsole.warn(warning.stack);// Print the stack trace});const process =require('node:process');process.on('warning',(warning) => {console.warn(warning.name);// Print the warning nameconsole.warn(warning.message);// Print the warning messageconsole.warn(warning.stack);// Print the stack trace});copy

$node>events.defaultMaxListeners = 1;>process.on('foo', () => {});>process.on('foo', () => {});>(node:38638) MaxListenersExceededWarning: Possible EventEmitter memory leakdetected. 2 foo listeners added. Use emitter.setMaxListeners() to increase limitcopy

$node --no-warnings>const p = process.on('warning', (warning) => console.warn('Do not do that!'));>events.defaultMaxListeners = 1;>process.on('foo', () => {});>process.on('foo', () => {});>Do notdo that!copy

import processfrom'node:process';// Begin reading from stdin so the process does not exit.process.stdin.resume();process.on('SIGINT',() => {console.log('Received SIGINT. Press Control-D to exit.');});// Using a single function to handle multiple signalsfunctionhandle(signal) {console.log(`Received${signal}`);}process.on('SIGINT', handle);process.on('SIGTERM', handle);const process =require('node:process');// Begin reading from stdin so the process does not exit.process.stdin.resume();process.on('SIGINT',() => {console.log('Received SIGINT. Press Control-D to exit.');});// Using a single function to handle multiple signalsfunctionhandle(signal) {console.log(`Received${signal}`);}process.on('SIGINT', handle);process.on('SIGTERM', handle);copy

process.abort()#

Theprocess.abort() method causes the Node.js process to exit immediately andgenerate a core file.

This feature is not available inWorker threads.

process.allowedNodeEnvironmentFlags#

• <Set>

Theprocess.allowedNodeEnvironmentFlags property is a special,read-onlySet of flags allowable within theNODE_OPTIONSenvironment variable.

process.allowedNodeEnvironmentFlags extendsSet, but overridesSet.prototype.has to recognize several different possible flagrepresentations.process.allowedNodeEnvironmentFlags.has() willreturntrue in the following cases:

• Flags may omit leading single (-) or double (--) dashes; e.g.,inspect-brk for--inspect-brk, orr for-r.
• Flags passed through to V8 (as listed in--v8-options) may replaceone or morenon-leading dashes for an underscore, or vice-versa;e.g.,--perf_basic_prof,--perf-basic-prof,--perf_basic-prof,etc.
• Flags may contain one or more equals (=) characters; allcharacters after and including the first equals will be ignored;e.g.,--stack-trace-limit=100.
• Flagsmust be allowable withinNODE_OPTIONS.

When iterating overprocess.allowedNodeEnvironmentFlags, flags willappear onlyonce; each will begin with one or more dashes. Flagspassed through to V8 will contain underscores instead of non-leadingdashes:

import { allowedNodeEnvironmentFlags }from'node:process';allowedNodeEnvironmentFlags.forEach((flag) => {// -r// --inspect-brk// --abort_on_uncaught_exception// ...});const { allowedNodeEnvironmentFlags } =require('node:process');allowedNodeEnvironmentFlags.forEach((flag) => {// -r// --inspect-brk// --abort_on_uncaught_exception// ...});copy

The methodsadd(),clear(), anddelete() ofprocess.allowedNodeEnvironmentFlags do nothing, and will failsilently.

If Node.js was compiledwithoutNODE_OPTIONS support (shown inprocess.config),process.allowedNodeEnvironmentFlags willcontain whatwould have been allowable.

process.arch#

• <string>

The operating system CPU architecture for which the Node.js binary was compiled.Possible values are:'arm','arm64','ia32','loong64','mips','mipsel','ppc64','riscv64','s390','s390x', and'x64'.

import { arch }from'node:process';console.log(`This processor architecture is${arch}`);const { arch } =require('node:process');console.log(`This processor architecture is${arch}`);copy

process.argv#

• <string[]>

Theprocess.argv property returns an array containing the command-linearguments passed when the Node.js process was launched. The first element willbeprocess.execPath. Seeprocess.argv0 if access to the original valueofargv[0] is needed. The second element will be the path to the JavaScriptfile being executed. The remaining elements will be any additional command-linearguments.

For example, assuming the following script forprocess-args.js:

import { argv }from'node:process';// print process.argvargv.forEach((val, index) => {console.log(`${index}:${val}`);});const { argv } =require('node:process');// print process.argvargv.forEach((val, index) => {console.log(`${index}:${val}`);});copy

Launching the Node.js process as:

node process-args.js one two=three fourcopy

Would generate the output:

0: /usr/local/bin/node1: /Users/mjr/work/node/process-args.js2: one3: two=three4: fourcopy

process.argv0#

• <string>

Theprocess.argv0 property stores a read-only copy of the original value ofargv[0] passed when Node.js starts.

$bash -c'exec -a customArgv0 ./node'>process.argv[0]'/Volumes/code/external/node/out/Release/node'>process.argv0'customArgv0'copy

process.availableMemory()#

• <number>

Gets the amount of free memory that is still available to the process(in bytes).

Seeuv_get_available_memory for moreinformation.

process.channel#

• <Object>

If the Node.js process was spawned with an IPC channel (see theChild Process documentation), theprocess.channelproperty is a reference to the IPC channel. If no IPC channel exists, thisproperty isundefined.

process.chdir(directory)#

• directory<string>

Theprocess.chdir() method changes the current working directory of theNode.js process or throws an exception if doing so fails (for instance, ifthe specifieddirectory does not exist).

import { chdir, cwd }from'node:process';console.log(`Starting directory:${cwd()}`);try {chdir('/tmp');console.log(`New directory:${cwd()}`);}catch (err) {console.error(`chdir:${err}`);}const { chdir, cwd } =require('node:process');console.log(`Starting directory:${cwd()}`);try {chdir('/tmp');console.log(`New directory:${cwd()}`);}catch (err) {console.error(`chdir:${err}`);}copy

This feature is not available inWorker threads.

process.config#

• <Object>

Theprocess.config property returns a frozenObject containing theJavaScript representation of the configure options used to compile the currentNode.js executable. This is the same as theconfig.gypi file that was producedwhen running the./configure script.

An example of the possible output looks like:

{target_defaults:   {cflags: [],default_configuration:'Release',defines: [],include_dirs: [],libraries: [] },variables:   {host_arch:'x64',napi_build_version:5,node_install_npm:'true',node_prefix:'',node_shared_cares:'false',node_shared_http_parser:'false',node_shared_libuv:'false',node_shared_zlib:'false',node_use_openssl:'true',node_shared_openssl:'false',target_arch:'x64',v8_use_snapshot:1   }}copy

process.connected#

• <boolean>

If the Node.js process is spawned with an IPC channel (see theChild ProcessandCluster documentation), theprocess.connected property will returntrue so long as the IPC channel is connected and will returnfalse afterprocess.disconnect() is called.

Onceprocess.connected isfalse, it is no longer possible to send messagesover the IPC channel usingprocess.send().

process.constrainedMemory()#

• <number>

Gets the amount of memory available to the process (in bytes) based onlimits imposed by the OS. If there is no such constraint, or the constraintis unknown,0 is returned.

Seeuv_get_constrained_memory for moreinformation.

process.cpuUsage([previousValue])#

• previousValue<Object> A previous return value from callingprocess.cpuUsage()
• Returns:<Object>
  • user<integer>
  • system<integer>

Theprocess.cpuUsage() method returns the user and system CPU time usage ofthe current process, in an object with propertiesuser andsystem, whosevalues are microsecond values (millionth of a second). These values measure timespent in user and system code respectively, and may end up being greater thanactual elapsed time if multiple CPU cores are performing work for this process.

The result of a previous call toprocess.cpuUsage() can be passed as theargument to the function, to get a diff reading.

import { cpuUsage }from'node:process';const startUsage =cpuUsage();// { user: 38579, system: 6986 }// spin the CPU for 500 millisecondsconst now =Date.now();while (Date.now() - now <500);console.log(cpuUsage(startUsage));// { user: 514883, system: 11226 }const { cpuUsage } =require('node:process');const startUsage =cpuUsage();// { user: 38579, system: 6986 }// spin the CPU for 500 millisecondsconst now =Date.now();while (Date.now() - now <500);console.log(cpuUsage(startUsage));// { user: 514883, system: 11226 }copy

process.cwd()#

• Returns:<string>

Theprocess.cwd() method returns the current working directory of the Node.jsprocess.

import { cwd }from'node:process';console.log(`Current directory:${cwd()}`);const { cwd } =require('node:process');console.log(`Current directory:${cwd()}`);copy

process.debugPort#

• <number>

The port used by the Node.js debugger when enabled.

import processfrom'node:process';process.debugPort =5858;const process =require('node:process');process.debugPort =5858;copy

process.disconnect()#

If the Node.js process is spawned with an IPC channel (see theChild ProcessandCluster documentation), theprocess.disconnect() method will close theIPC channel to the parent process, allowing the child process to exit gracefullyonce there are no other connections keeping it alive.

The effect of callingprocess.disconnect() is the same as callingChildProcess.disconnect() from the parent process.

If the Node.js process was not spawned with an IPC channel,process.disconnect() will beundefined.

process.dlopen(module, filename[, flags])#

• module<Object>
• filename<string>
• flags<os.constants.dlopen>Default:os.constants.dlopen.RTLD_LAZY

Theprocess.dlopen() method allows dynamically loading shared objects. It isprimarily used byrequire() to load C++ Addons, and should not be useddirectly, except in special cases. In other words,require() should bepreferred overprocess.dlopen() unless there are specific reasons such ascustom dlopen flags or loading from ES modules.

Theflags argument is an integer that allows to specify dlopenbehavior. See theos.constants.dlopen documentation for details.

An important requirement when callingprocess.dlopen() is that themoduleinstance must be passed. Functions exported by the C++ Addon are thenaccessible viamodule.exports.

The example below shows how to load a C++ Addon, namedlocal.node,that exports afoo function. All the symbols are loaded beforethe call returns, by passing theRTLD_NOW constant. In this examplethe constant is assumed to be available.

import { dlopen }from'node:process';import { constants }from'node:os';import { fileURLToPath }from'node:url';constmodule = {exports: {} };dlopen(module,fileURLToPath(newURL('local.node',import.meta.url)),       constants.dlopen.RTLD_NOW);module.exports.foo();const { dlopen } =require('node:process');const { constants } =require('node:os');const { join } =require('node:path');constmodule = {exports: {} };dlopen(module,join(__dirname,'local.node'), constants.dlopen.RTLD_NOW);module.exports.foo();copy

process.emitWarning(warning[, options])#

• warning<string> |<Error> The warning to emit.
• options<Object>
  • type<string> Whenwarning is aString,type is the name to usefor thetype of warning being emitted.Default:'Warning'.
  • code<string> A unique identifier for the warning instance being emitted.
  • ctor<Function> Whenwarning is aString,ctor is an optionalfunction used to limit the generated stack trace.Default:process.emitWarning.
  • detail<string> Additional text to include with the error.

Theprocess.emitWarning() method can be used to emit custom or applicationspecific process warnings. These can be listened for by adding a handler to the'warning' event.

import { emitWarning }from'node:process';// Emit a warning with a code and additional detail.emitWarning('Something happened!', {code:'MY_WARNING',detail:'This is some additional information',});// Emits:// (node:56338) [MY_WARNING] Warning: Something happened!// This is some additional informationconst { emitWarning } =require('node:process');// Emit a warning with a code and additional detail.emitWarning('Something happened!', {code:'MY_WARNING',detail:'This is some additional information',});// Emits:// (node:56338) [MY_WARNING] Warning: Something happened!// This is some additional informationcopy

In this example, anError object is generated internally byprocess.emitWarning() and passed through to the'warning' handler.

import processfrom'node:process';process.on('warning',(warning) => {console.warn(warning.name);// 'Warning'console.warn(warning.message);// 'Something happened!'console.warn(warning.code);// 'MY_WARNING'console.warn(warning.stack);// Stack traceconsole.warn(warning.detail);// 'This is some additional information'});const process =require('node:process');process.on('warning',(warning) => {console.warn(warning.name);// 'Warning'console.warn(warning.message);// 'Something happened!'console.warn(warning.code);// 'MY_WARNING'console.warn(warning.stack);// Stack traceconsole.warn(warning.detail);// 'This is some additional information'});copy

Ifwarning is passed as anError object, theoptions argument is ignored.

process.emitWarning(warning[, type[, code]][, ctor])#

• warning<string> |<Error> The warning to emit.
• type<string> Whenwarning is aString,type is the name to usefor thetype of warning being emitted.Default:'Warning'.
• code<string> A unique identifier for the warning instance being emitted.
• ctor<Function> Whenwarning is aString,ctor is an optionalfunction used to limit the generated stack trace.Default:process.emitWarning.

Theprocess.emitWarning() method can be used to emit custom or applicationspecific process warnings. These can be listened for by adding a handler to the'warning' event.

import { emitWarning }from'node:process';// Emit a warning using a string.emitWarning('Something happened!');// Emits: (node: 56338) Warning: Something happened!const { emitWarning } =require('node:process');// Emit a warning using a string.emitWarning('Something happened!');// Emits: (node: 56338) Warning: Something happened!copy

import { emitWarning }from'node:process';// Emit a warning using a string and a type.emitWarning('Something Happened!','CustomWarning');// Emits: (node:56338) CustomWarning: Something Happened!const { emitWarning } =require('node:process');// Emit a warning using a string and a type.emitWarning('Something Happened!','CustomWarning');// Emits: (node:56338) CustomWarning: Something Happened!copy

import { emitWarning }from'node:process';emitWarning('Something happened!','CustomWarning','WARN001');// Emits: (node:56338) [WARN001] CustomWarning: Something happened!const { emitWarning } =require('node:process');process.emitWarning('Something happened!','CustomWarning','WARN001');// Emits: (node:56338) [WARN001] CustomWarning: Something happened!copy

In each of the previous examples, anError object is generated internally byprocess.emitWarning() and passed through to the'warning'handler.

import processfrom'node:process';process.on('warning',(warning) => {console.warn(warning.name);console.warn(warning.message);console.warn(warning.code);console.warn(warning.stack);});const process =require('node:process');process.on('warning',(warning) => {console.warn(warning.name);console.warn(warning.message);console.warn(warning.code);console.warn(warning.stack);});copy

Ifwarning is passed as anError object, it will be passed through to the'warning' event handler unmodified (and the optionaltype,code andctor arguments will be ignored):

import { emitWarning }from'node:process';// Emit a warning using an Error object.const myWarning =newError('Something happened!');// Use the Error name property to specify the type namemyWarning.name ='CustomWarning';myWarning.code ='WARN001';emitWarning(myWarning);// Emits: (node:56338) [WARN001] CustomWarning: Something happened!const { emitWarning } =require('node:process');// Emit a warning using an Error object.const myWarning =newError('Something happened!');// Use the Error name property to specify the type namemyWarning.name ='CustomWarning';myWarning.code ='WARN001';emitWarning(myWarning);// Emits: (node:56338) [WARN001] CustomWarning: Something happened!copy

ATypeError is thrown ifwarning is anything other than a string orErrorobject.

While process warnings useError objects, the process warningmechanism isnot a replacement for normal error handling mechanisms.

The following additional handling is implemented if the warningtype is'DeprecationWarning':

• If the--throw-deprecation command-line flag is used, the deprecationwarning is thrown as an exception rather than being emitted as an event.
• If the--no-deprecation command-line flag is used, the deprecationwarning is suppressed.
• If the--trace-deprecation command-line flag is used, the deprecationwarning is printed tostderr along with the full stack trace.

import { emitWarning }from'node:process';functionemitMyWarning() {if (!emitMyWarning.warned) {    emitMyWarning.warned =true;emitWarning('Only warn once!');  }}emitMyWarning();// Emits: (node: 56339) Warning: Only warn once!emitMyWarning();// Emits nothingconst { emitWarning } =require('node:process');functionemitMyWarning() {if (!emitMyWarning.warned) {    emitMyWarning.warned =true;emitWarning('Only warn once!');  }}emitMyWarning();// Emits: (node: 56339) Warning: Only warn once!emitMyWarning();// Emits nothingcopy

process.env#

• <Object>

Theprocess.env property returns an object containing the user environment.Seeenviron(7).

An example of this object looks like:

{TERM:'xterm-256color',SHELL:'/usr/local/bin/bash',USER:'maciej',PATH:'~/.bin/:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin',PWD:'/Users/maciej',EDITOR:'vim',SHLVL:'1',HOME:'/Users/maciej',LOGNAME:'maciej',_:'/usr/local/bin/node'}copy

It is possible to modify this object, but such modifications will not bereflected outside the Node.js process, or (unless explicitly requested)to otherWorker threads.In other words, the following example would not work:

node -e'process.env.foo = "bar"' &&echo$foocopy

While the following will:

import { env }from'node:process';env.foo ='bar';console.log(env.foo);const { env } =require('node:process');env.foo ='bar';console.log(env.foo);copy

Assigning a property onprocess.env will implicitly convert the valueto a string.This behavior is deprecated. Future versions of Node.js maythrow an error when the value is not a string, number, or boolean.

import { env }from'node:process';env.test =null;console.log(env.test);// => 'null'env.test =undefined;console.log(env.test);// => 'undefined'const { env } =require('node:process');env.test =null;console.log(env.test);// => 'null'env.test =undefined;console.log(env.test);// => 'undefined'copy

Usedelete to delete a property fromprocess.env.

import { env }from'node:process';env.TEST =1;delete env.TEST;console.log(env.TEST);// => undefinedconst { env } =require('node:process');env.TEST =1;delete env.TEST;console.log(env.TEST);// => undefinedcopy

On Windows operating systems, environment variables are case-insensitive.

import { env }from'node:process';env.TEST =1;console.log(env.test);// => 1const { env } =require('node:process');env.TEST =1;console.log(env.test);// => 1copy

Unless explicitly specified when creating aWorker instance,eachWorker thread has its own copy ofprocess.env, based on itsparent thread'sprocess.env, or whatever was specified as theenv optionto theWorker constructor. Changes toprocess.env will not be visibleacrossWorker threads, and only the main thread can make changes thatare visible to the operating system or to native add-ons. On Windows, a copy ofprocess.env on aWorker instance operates in a case-sensitive mannerunlike the main thread.

process.execArgv#

• <string[]>

Theprocess.execArgv property returns the set of Node.js-specific command-lineoptions passed when the Node.js process was launched. These options do notappear in the array returned by theprocess.argv property, and do notinclude the Node.js executable, the name of the script, or any options followingthe script name. These options are useful in order to spawn child processes withthe same execution environment as the parent.

node --icu-data-dir=./foo --require ./bar.js script.js --versioncopy

Results inprocess.execArgv:

["--icu-data-dir=./foo","--require","./bar.js"]copy

Andprocess.argv:

['/usr/local/bin/node','script.js','--version']copy

Refer toWorker constructor for the detailed behavior of workerthreads with this property.

process.execPath#

• <string>

Theprocess.execPath property returns the absolute pathname of the executablethat started the Node.js process. Symbolic links, if any, are resolved.

'/usr/local/bin/node'copy

process.execve(file[, args[, env]])#

• file<string> The name or path of the executable file to run.
• args<string[]> List of string arguments. No argument can contain a null-byte (\u0000).
• env<Object> Environment key-value pairs.No key or value can contain a null-byte (\u0000).Default:process.env.

Replaces the current process with a new process.

This is achieved by using theexecve POSIX function and therefore no memory or otherresources from the current process are preserved, except for the standard input,standard output and standard error file descriptor.

All other resources are discarded by the system when the processes are swapped, without triggeringany exit or close events and without running any cleanup handler.

This function will never return, unless an error occurred.

This function is not available on Windows or IBM i.

process.exit([code])#

• code<integer> |<string> |<null> |<undefined> The exit code. For string type, onlyinteger strings (e.g.,'1') are allowed.Default:0.

Theprocess.exit() method instructs Node.js to terminate the processsynchronously with an exit status ofcode. Ifcode is omitted, exit useseither the 'success' code0 or the value ofprocess.exitCode if it has beenset. Node.js will not terminate until all the'exit' event listeners arecalled.

To exit with a 'failure' code:

import { exit }from'node:process';exit(1);const { exit } =require('node:process');exit(1);copy

The shell that executed Node.js should see the exit code as1.

Callingprocess.exit() will force the process to exit as quickly as possibleeven if there are still asynchronous operations pending that have not yetcompleted fully, including I/O operations toprocess.stdout andprocess.stderr.

In most situations, it is not actually necessary to callprocess.exit()explicitly. The Node.js process will exit on its ownif there is no additionalwork pending in the event loop. Theprocess.exitCode property can be set totell the process which exit code to use when the process exits gracefully.

For instance, the following example illustrates amisuse of theprocess.exit() method that could lead to data printed to stdout beingtruncated and lost:

import { exit }from'node:process';// This is an example of what *not* to do:if (someConditionNotMet()) {printUsageToStdout();exit(1);}const { exit } =require('node:process');// This is an example of what *not* to do:if (someConditionNotMet()) {printUsageToStdout();exit(1);}copy

The reason this is problematic is because writes toprocess.stdout in Node.jsare sometimesasynchronous and may occur over multiple ticks of the Node.jsevent loop. Callingprocess.exit(), however, forces the process to exitbefore those additional writes tostdout can be performed.

Rather than callingprocess.exit() directly, the codeshould set theprocess.exitCode and allow the process to exit naturally by avoidingscheduling any additional work for the event loop:

import processfrom'node:process';// How to properly set the exit code while letting// the process exit gracefully.if (someConditionNotMet()) {printUsageToStdout();  process.exitCode =1;}const process =require('node:process');// How to properly set the exit code while letting// the process exit gracefully.if (someConditionNotMet()) {printUsageToStdout();  process.exitCode =1;}copy

If it is necessary to terminate the Node.js process due to an error condition,throwing anuncaught error and allowing the process to terminate accordinglyis safer than callingprocess.exit().

InWorker threads, this function stops the current thread ratherthan the current process.

process.exitCode#

• <integer> |<string> |<null> |<undefined> The exit code. For string type, onlyinteger strings (e.g.,'1') are allowed.Default:undefined.

A number which will be the process exit code, when the process eitherexits gracefully, or is exited viaprocess.exit() without specifyinga code.

The value ofprocess.exitCode can be updated by either assigning a value toprocess.exitCode or by passing an argument toprocess.exit():

$node -e'process.exitCode = 9';echo $?9$node -e'process.exit(42)';echo $?42$node -e'process.exitCode = 9; process.exit(42)';echo $?42copy

The value can also be set implicitly by Node.js when unrecoverable errors occur (e.g.such as the encountering of an unsettled top-level await). However explicitmanipulations of the exit code always take precedence over implicit ones:

$node --input-type=module -e'await new Promise(() => {})';echo $?13$node --input-type=module -e'process.exitCode = 9; await new Promise(() => {})';echo $?9copy

process.features.cached_builtins#

• <boolean>

A boolean value that istrue if the current Node.js build is caching builtin modules.

process.features.debug#

• <boolean>

A boolean value that istrue if the current Node.js build is a debug build.

process.features.inspector#

• <boolean>

A boolean value that istrue if the current Node.js build includes the inspector.

process.features.ipv6#

• <boolean>

A boolean value that istrue if the current Node.js build includes support for IPv6.

Since all Node.js builds have IPv6 support, this value is alwaystrue.

process.features.require_module#

• <boolean>

A boolean value that istrue if the current Node.js build supportsloading ECMAScript modules usingrequire().

process.features.tls#

• <boolean>

A boolean value that istrue if the current Node.js build includes support for TLS.

process.features.tls_alpn#

• <boolean>

A boolean value that istrue if the current Node.js build includes support for ALPN in TLS.

In Node.js 11.0.0 and later versions, the OpenSSL dependencies feature unconditional ALPN support.This value is therefore identical to that ofprocess.features.tls.

process.features.tls_ocsp#

• <boolean>

A boolean value that istrue if the current Node.js build includes support for OCSP in TLS.

In Node.js 11.0.0 and later versions, the OpenSSL dependencies feature unconditional OCSP support.This value is therefore identical to that ofprocess.features.tls.

process.features.tls_sni#

• <boolean>

A boolean value that istrue if the current Node.js build includes support for SNI in TLS.

In Node.js 11.0.0 and later versions, the OpenSSL dependencies feature unconditional SNI support.This value is therefore identical to that ofprocess.features.tls.

process.features.typescript#

• <boolean> |<string>

A value that is"strip" by default,"transform" if Node.js is run with--experimental-transform-types, andfalse ifNode.js is run with--no-experimental-strip-types.

process.features.uv#

• <boolean>

A boolean value that istrue if the current Node.js build includes support for libuv.

Since it's not possible to build Node.js without libuv, this value is alwaystrue.

process.finalization.register(ref, callback)#

• ref<Object> |<Function> The reference to the resource that is being tracked.
• callback<Function> The callback function to be called when the resourceis finalized.
  • ref<Object> |<Function> The reference to the resource that is being tracked.
  • event<string> The event that triggered the finalization. Defaults to 'exit'.

This function registers a callback to be called when the process emits theexitevent if theref object was not garbage collected. If the objectref was garbage collectedbefore theexit event is emitted, the callback will be removed from the finalization registry,and it will not be called on process exit.

Inside the callback you can release the resources allocated by theref object.Be aware that all limitations applied to thebeforeExit event are also applied to thecallback function,this means that there is a possibility that the callback will not be called under special circumstances.

The idea of ​​this function is to help you free up resources when the starts process exiting,but also let the object be garbage collected if it is no longer being used.

Eg: you can register an object that contains a buffer, you want to make sure that buffer is releasedwhen the process exit, but if the object is garbage collected before the process exit, we no longerneed to release the buffer, so in this case we just remove the callback from the finalization registry.

const { finalization } =require('node:process');// Please make sure that the function passed to finalization.register()// does not create a closure around unnecessary objects.functiononFinalize(obj, event) {// You can do whatever you want with the object  obj.dispose();}functionsetup() {// This object can be safely garbage collected,// and the resulting shutdown function will not be called.// There are no leaks.const myDisposableObject = {dispose() {// Free your resources synchronously    },  };  finalization.register(myDisposableObject, onFinalize);}setup();import { finalization }from'node:process';// Please make sure that the function passed to finalization.register()// does not create a closure around unnecessary objects.functiononFinalize(obj, event) {// You can do whatever you want with the object  obj.dispose();}functionsetup() {// This object can be safely garbage collected,// and the resulting shutdown function will not be called.// There are no leaks.const myDisposableObject = {dispose() {// Free your resources synchronously    },  };  finalization.register(myDisposableObject, onFinalize);}setup();copy

The code above relies on the following assumptions:

• arrow functions are avoided
• regular functions are recommended to be within the global context (root)

Regular functionscould reference the context where theobj lives, making theobj not garbage collectible.

Arrow functions will hold the previous context. Consider, for example:

classTest {constructor() {    finalization.register(this,(ref) => ref.dispose());// Even something like this is highly discouraged// finalization.register(this, () => this.dispose());  }dispose() {}}copy

It is very unlikely (not impossible) that this object will be garbage collected,but if it is not,dispose will be called whenprocess.exit is called.

Be careful and avoid relying on this feature for the disposal of critical resources,as it is not guaranteed that the callback will be called under all circumstances.

process.finalization.registerBeforeExit(ref, callback)#

• ref<Object> |<Function> The referenceto the resource that is being tracked.
• callback<Function> The callback function to be called when the resourceis finalized.
  • ref<Object> |<Function> The reference to the resource that is being tracked.
  • event<string> The event that triggered the finalization. Defaults to 'beforeExit'.

This function behaves exactly like theregister, except that the callback will be calledwhen the process emits thebeforeExit event ifref object was not garbage collected.

Be aware that all limitations applied to thebeforeExit event are also applied to thecallback function,this means that there is a possibility that the callback will not be called under special circumstances.

process.finalization.unregister(ref)#

• ref<Object> |<Function> The referenceto the resource that was registered previously.

This function remove the register of the object from the finalizationregistry, so the callback will not be called anymore.

const { finalization } =require('node:process');// Please make sure that the function passed to finalization.register()// does not create a closure around unnecessary objects.functiononFinalize(obj, event) {// You can do whatever you want with the object  obj.dispose();}functionsetup() {// This object can be safely garbage collected,// and the resulting shutdown function will not be called.// There are no leaks.const myDisposableObject = {dispose() {// Free your resources synchronously    },  };  finalization.register(myDisposableObject, onFinalize);// Do something  myDisposableObject.dispose();  finalization.unregister(myDisposableObject);}setup();import { finalization }from'node:process';// Please make sure that the function passed to finalization.register()// does not create a closure around unnecessary objects.functiononFinalize(obj, event) {// You can do whatever you want with the object  obj.dispose();}functionsetup() {// This object can be safely garbage collected,// and the resulting shutdown function will not be called.// There are no leaks.const myDisposableObject = {dispose() {// Free your resources synchronously    },  };// Please make sure that the function passed to finalization.register()// does not create a closure around unnecessary objects.functiononFinalize(obj, event) {// You can do whatever you want with the object    obj.dispose();  }  finalization.register(myDisposableObject, onFinalize);// Do something  myDisposableObject.dispose();  finalization.unregister(myDisposableObject);}setup();copy

process.getActiveResourcesInfo()#

• Returns:<string[]>

Theprocess.getActiveResourcesInfo() method returns an array of stringscontaining the types of the active resources that are currently keeping theevent loop alive.

import { getActiveResourcesInfo }from'node:process';import {setTimeout }from'node:timers';console.log('Before:',getActiveResourcesInfo());setTimeout(() => {},1000);console.log('After:',getActiveResourcesInfo());// Prints://   Before: [ 'CloseReq', 'TTYWrap', 'TTYWrap', 'TTYWrap' ]//   After: [ 'CloseReq', 'TTYWrap', 'TTYWrap', 'TTYWrap', 'Timeout' ]const { getActiveResourcesInfo } =require('node:process');const {setTimeout } =require('node:timers');console.log('Before:',getActiveResourcesInfo());setTimeout(() => {},1000);console.log('After:',getActiveResourcesInfo());// Prints://   Before: [ 'TTYWrap', 'TTYWrap', 'TTYWrap' ]//   After: [ 'TTYWrap', 'TTYWrap', 'TTYWrap', 'Timeout' ]copy

process.getBuiltinModule(id)#

• id<string> ID of the built-in module being requested.
• Returns:<Object> |<undefined>

process.getBuiltinModule(id) provides a way to load built-in modulesin a globally available function. ES Modules that need to supportother environments can use it to conditionally load a Node.js built-inwhen it is run in Node.js, without having to deal with the resolutionerror that can be thrown byimport in a non-Node.js environment orhaving to use dynamicimport() which either turns the module intoan asynchronous module, or turns a synchronous API into an asynchronous one.

if (globalThis.process?.getBuiltinModule) {// Run in Node.js, use the Node.js fs module.const fs = globalThis.process.getBuiltinModule('fs');// If `require()` is needed to load user-modules, use createRequire()constmodule = globalThis.process.getBuiltinModule('module');constrequire =module.createRequire(import.meta.url);const foo =require('foo');}copy

Ifid specifies a built-in module available in the current Node.js process,process.getBuiltinModule(id) method returns the corresponding built-inmodule. Ifid does not correspond to any built-in module,undefinedis returned.

process.getBuiltinModule(id) accepts built-in module IDs that are recognizedbymodule.isBuiltin(id). Some built-in modules must be loaded with thenode: prefix, seebuilt-in modules with mandatorynode: prefix.The references returned byprocess.getBuiltinModule(id) always point tothe built-in module corresponding toid even if users modifyrequire.cache so thatrequire(id) returns something else.

process.getegid()#

Theprocess.getegid() method returns the numerical effective group identityof the Node.js process. (Seegetegid(2).)

import processfrom'node:process';if (process.getegid) {console.log(`Current gid:${process.getegid()}`);}const process =require('node:process');if (process.getegid) {console.log(`Current gid:${process.getegid()}`);}copy

This function is only available on POSIX platforms (i.e. not Windows orAndroid).

process.geteuid()#

• Returns:<Object>

Theprocess.geteuid() method returns the numerical effective user identity ofthe process. (Seegeteuid(2).)

import processfrom'node:process';if (process.geteuid) {console.log(`Current uid:${process.geteuid()}`);}const process =require('node:process');if (process.geteuid) {console.log(`Current uid:${process.geteuid()}`);}copy

This function is only available on POSIX platforms (i.e. not Windows orAndroid).

process.getgid()#

• Returns:<Object>

Theprocess.getgid() method returns the numerical group identity of theprocess. (Seegetgid(2).)

import processfrom'node:process';if (process.getgid) {console.log(`Current gid:${process.getgid()}`);}const process =require('node:process');if (process.getgid) {console.log(`Current gid:${process.getgid()}`);}copy

This function is only available on POSIX platforms (i.e. not Windows orAndroid).

process.getgroups()#

• Returns:<integer[]>

Theprocess.getgroups() method returns an array with the supplementary groupIDs. POSIX leaves it unspecified if the effective group ID is included butNode.js ensures it always is.

import processfrom'node:process';if (process.getgroups) {console.log(process.getgroups());// [ 16, 21, 297 ]}const process =require('node:process');if (process.getgroups) {console.log(process.getgroups());// [ 16, 21, 297 ]}copy

This function is only available on POSIX platforms (i.e. not Windows orAndroid).

process.getuid()#

• Returns:<integer>

Theprocess.getuid() method returns the numeric user identity of the process.(Seegetuid(2).)

import processfrom'node:process';if (process.getuid) {console.log(`Current uid:${process.getuid()}`);}const process =require('node:process');if (process.getuid) {console.log(`Current uid:${process.getuid()}`);}copy

This function not available on Windows.

process.hasUncaughtExceptionCaptureCallback()#

• Returns:<boolean>

Indicates whether a callback has been set usingprocess.setUncaughtExceptionCaptureCallback().

process.hrtime([time])#

• time<integer[]> The result of a previous call toprocess.hrtime()
• Returns:<integer[]>

This is the legacy version ofprocess.hrtime.bigint()beforebigint was introduced in JavaScript.

Theprocess.hrtime() method returns the current high-resolution real timein a[seconds, nanoseconds] tupleArray, wherenanoseconds is theremaining part of the real time that can't be represented in second precision.

time is an optional parameter that must be the result of a previousprocess.hrtime() call to diff with the current time. If the parameterpassed in is not a tupleArray, aTypeError will be thrown. Passing in auser-defined array instead of the result of a previous call toprocess.hrtime() will lead to undefined behavior.

These times are relative to an arbitrary time in thepast, and not related to the time of day and therefore not subject to clockdrift. The primary use is for measuring performance between intervals:

import { hrtime }from'node:process';constNS_PER_SEC =1e9;const time =hrtime();// [ 1800216, 25 ]setTimeout(() => {const diff =hrtime(time);// [ 1, 552 ]console.log(`Benchmark took${diff[0] * NS_PER_SEC + diff[1]} nanoseconds`);// Benchmark took 1000000552 nanoseconds},1000);const { hrtime } =require('node:process');constNS_PER_SEC =1e9;const time =hrtime();// [ 1800216, 25 ]setTimeout(() => {const diff =hrtime(time);// [ 1, 552 ]console.log(`Benchmark took${diff[0] * NS_PER_SEC + diff[1]} nanoseconds`);// Benchmark took 1000000552 nanoseconds},1000);copy

process.hrtime.bigint()#

• Returns:<bigint>

Thebigint version of theprocess.hrtime() method returning thecurrent high-resolution real time in nanoseconds as abigint.

Unlikeprocess.hrtime(), it does not support an additionaltimeargument since the difference can just be computed directlyby subtraction of the twobigints.

import { hrtime }from'node:process';const start = hrtime.bigint();// 191051479007711nsetTimeout(() => {const end = hrtime.bigint();// 191052633396993nconsole.log(`Benchmark took${end - start} nanoseconds`);// Benchmark took 1154389282 nanoseconds},1000);const { hrtime } =require('node:process');const start = hrtime.bigint();// 191051479007711nsetTimeout(() => {const end = hrtime.bigint();// 191052633396993nconsole.log(`Benchmark took${end - start} nanoseconds`);// Benchmark took 1154389282 nanoseconds},1000);copy

process.initgroups(user, extraGroup)#

• user<string> |<number> The user name or numeric identifier.
• extraGroup<string> |<number> A group name or numeric identifier.

Theprocess.initgroups() method reads the/etc/group file and initializesthe group access list, using all groups of which the user is a member. This isa privileged operation that requires that the Node.js process either haverootaccess or theCAP_SETGID capability.

Use care when dropping privileges:

import { getgroups, initgroups, setgid }from'node:process';console.log(getgroups());// [ 0 ]initgroups('nodeuser',1000);// switch userconsole.log(getgroups());// [ 27, 30, 46, 1000, 0 ]setgid(1000);// drop root gidconsole.log(getgroups());// [ 27, 30, 46, 1000 ]const { getgroups, initgroups, setgid } =require('node:process');console.log(getgroups());// [ 0 ]initgroups('nodeuser',1000);// switch userconsole.log(getgroups());// [ 27, 30, 46, 1000, 0 ]setgid(1000);// drop root gidconsole.log(getgroups());// [ 27, 30, 46, 1000 ]copy

This function is only available on POSIX platforms (i.e. not Windows orAndroid).This feature is not available inWorker threads.

process.kill(pid[, signal])#

• pid<number> A process ID
• signal<string> |<number> The signal to send, either as a string or number.Default:'SIGTERM'.

Theprocess.kill() method sends thesignal to the process identified bypid.

Signal names are strings such as'SIGINT' or'SIGHUP'. SeeSignal Eventsandkill(2) for more information.

This method will throw an error if the targetpid does not exist. As a specialcase, a signal of0 can be used to test for the existence of a process.Windows platforms will throw an error if thepid is used to kill a processgroup.

Even though the name of this function isprocess.kill(), it is really just asignal sender, like thekill system call. The signal sent may do somethingother than kill the target process.

import process, { kill }from'node:process';process.on('SIGHUP',() => {console.log('Got SIGHUP signal.');});setTimeout(() => {console.log('Exiting.');  process.exit(0);},100);kill(process.pid,'SIGHUP');const process =require('node:process');process.on('SIGHUP',() => {console.log('Got SIGHUP signal.');});setTimeout(() => {console.log('Exiting.');  process.exit(0);},100);process.kill(process.pid,'SIGHUP');copy

WhenSIGUSR1 is received by a Node.js process, Node.js will start thedebugger. SeeSignal Events.

process.loadEnvFile(path)#

• path<string> |<URL> |<Buffer> |<undefined>.Default:'./.env'

Loads the.env file intoprocess.env. Usage ofNODE_OPTIONSin the.env file will not have any effect on Node.js.

const { loadEnvFile } =require('node:process');loadEnvFile();import { loadEnvFile }from'node:process';loadEnvFile();copy

process.mainModule#

• <Object>

Theprocess.mainModule property provides an alternative way of retrievingrequire.main. The difference is that if the main module changes atruntime,require.main may still refer to the original main module inmodules that were required before the change occurred. Generally, it'ssafe to assume that the two refer to the same module.

As withrequire.main,process.mainModule will beundefined if thereis no entry script.

process.memoryUsage()#

• Returns:<Object>
  • rss<integer>
  • heapTotal<integer>
  • heapUsed<integer>
  • external<integer>
  • arrayBuffers<integer>

Returns an object describing the memory usage of the Node.js process measured inbytes.

import { memoryUsage }from'node:process';console.log(memoryUsage());// Prints:// {//  rss: 4935680,//  heapTotal: 1826816,//  heapUsed: 650472,//  external: 49879,//  arrayBuffers: 9386// }const { memoryUsage } =require('node:process');console.log(memoryUsage());// Prints:// {//  rss: 4935680,//  heapTotal: 1826816,//  heapUsed: 650472,//  external: 49879,//  arrayBuffers: 9386// }copy

• heapTotal andheapUsed refer to V8's memory usage.
• external refers to the memory usage of C++ objects bound to JavaScriptobjects managed by V8.
• rss, Resident Set Size, is the amount of space occupied in the mainmemory device (that is a subset of the total allocated memory) for theprocess, including all C++ and JavaScript objects and code.
• arrayBuffers refers to memory allocated forArrayBuffers andSharedArrayBuffers, including all Node.jsBuffers.This is also included in theexternal value. When Node.js is used as anembedded library, this value may be0 because allocations forArrayBuffersmay not be tracked in that case.

When usingWorker threads,rss will be a value that is valid for theentire process, while the other fields will only refer to the current thread.

Theprocess.memoryUsage() method iterates over each page to gatherinformation about memory usage which might be slow depending on theprogram memory allocations.

process.memoryUsage.rss()#

• Returns:<integer>

Theprocess.memoryUsage.rss() method returns an integer representing theResident Set Size (RSS) in bytes.

The Resident Set Size, is the amount of space occupied in the mainmemory device (that is a subset of the total allocated memory) for theprocess, including all C++ and JavaScript objects and code.

This is the same value as therss property provided byprocess.memoryUsage()butprocess.memoryUsage.rss() is faster.

import { memoryUsage }from'node:process';console.log(memoryUsage.rss());// 35655680const { memoryUsage } =require('node:process');console.log(memoryUsage.rss());// 35655680copy

process.nextTick(callback[, ...args])#

• callback<Function>
• ...args<any> Additional arguments to pass when invoking thecallback

process.nextTick() addscallback to the "next tick queue". This queue isfully drained after the current operation on the JavaScript stack runs tocompletion and before the event loop is allowed to continue. It's possible tocreate an infinite loop if one were to recursively callprocess.nextTick().See theEvent Loop guide for more background.

import { nextTick }from'node:process';console.log('start');nextTick(() => {console.log('nextTick callback');});console.log('scheduled');// Output:// start// scheduled// nextTick callbackconst { nextTick } =require('node:process');console.log('start');nextTick(() => {console.log('nextTick callback');});console.log('scheduled');// Output:// start// scheduled// nextTick callbackcopy

This is important when developing APIs in order to give users the opportunityto assign event handlersafter an object has been constructed but before anyI/O has occurred:

import { nextTick }from'node:process';functionMyThing(options) {this.setupOptions(options);nextTick(() => {this.startDoingStuff();  });}const thing =newMyThing();thing.getReadyForStuff();// thing.startDoingStuff() gets called now, not before.const { nextTick } =require('node:process');functionMyThing(options) {this.setupOptions(options);nextTick(() => {this.startDoingStuff();  });}const thing =newMyThing();thing.getReadyForStuff();// thing.startDoingStuff() gets called now, not before.copy

It is very important for APIs to be either 100% synchronous or 100%asynchronous. Consider this example:

// WARNING!  DO NOT USE!  BAD UNSAFE HAZARD!functionmaybeSync(arg, cb) {if (arg) {cb();return;  }  fs.stat('file', cb);}copy

This API is hazardous because in the following case:

const maybeTrue =Math.random() >0.5;maybeSync(maybeTrue,() => {foo();});bar();copy

It is not clear whetherfoo() orbar() will be called first.

The following approach is much better:

import { nextTick }from'node:process';functiondefinitelyAsync(arg, cb) {if (arg) {nextTick(cb);return;  }  fs.stat('file', cb);}const { nextTick } =require('node:process');functiondefinitelyAsync(arg, cb) {if (arg) {nextTick(cb);return;  }  fs.stat('file', cb);}copy

import { nextTick }from'node:process';Promise.resolve().then(() =>console.log('resolve'));queueMicrotask(() =>console.log('microtask'));nextTick(() =>console.log('nextTick'));// Output:// resolve// microtask// nextTickconst { nextTick } =require('node:process');Promise.resolve().then(() =>console.log('resolve'));queueMicrotask(() =>console.log('microtask'));nextTick(() =>console.log('nextTick'));// Output:// nextTick// resolve// microtaskcopy

console.log('start');queueMicrotask(() => {console.log('microtask callback');});console.log('scheduled');// Output:// start// scheduled// microtask callbackcopy

functiondeferred(a, b) {console.log('microtask', a + b);}console.log('start');queueMicrotask(deferred.bind(undefined,1,2));console.log('scheduled');// Output:// start// scheduled// microtask 3copy

process.noDeprecation#

• <boolean>

Theprocess.noDeprecation property indicates whether the--no-deprecationflag is set on the current Node.js process. See the documentation forthe'warning' event and theemitWarning() method for more information about thisflag's behavior.

process.permission#

• <Object>

This API is available through the--permission flag.

process.permission is an object whose methods are used to manage permissionsfor the current process. Additional documentation is available in thePermission Model.

// Check if the process has permission to read the README fileprocess.permission.has('fs.read','./README.md');// Check if the process has read permission operationsprocess.permission.has('fs.read');copy

process.pid#

• <integer>

Theprocess.pid property returns the PID of the process.

import { pid }from'node:process';console.log(`This process is pid${pid}`);const { pid } =require('node:process');console.log(`This process is pid${pid}`);copy

process.platform#

• <string>

Theprocess.platform property returns a string identifying the operatingsystem platform for which the Node.js binary was compiled.

Currently possible values are:

• 'aix'
• 'darwin'
• 'freebsd'
• 'linux'
• 'openbsd'
• 'sunos'
• 'win32'

import { platform }from'node:process';console.log(`This platform is${platform}`);const { platform } =require('node:process');console.log(`This platform is${platform}`);copy

The value'android' may also be returned if the Node.js is built on theAndroid operating system. However, Android support in Node.jsis experimental.

process.ppid#

• <integer>

Theprocess.ppid property returns the PID of the parent of thecurrent process.

import { ppid }from'node:process';console.log(`The parent process is pid${ppid}`);const { ppid } =require('node:process');console.log(`The parent process is pid${ppid}`);copy

process.ref(maybeRefable)#

• maybeRefable<any> An object that may be "refable".

An object is "refable" if it implements the Node.js "Refable protocol".Specifically, this means that the object implements theSymbol.for('nodejs.ref')andSymbol.for('nodejs.unref') methods. "Ref'd" objects will keep the Node.jsevent loop alive, while "unref'd" objects will not. Historically, this wasimplemented by usingref() andunref() methods directly on the objects.This pattern, however, is being deprecated in favor of the "Refable protocol"in order to better support Web Platform API types whose APIs cannot be modifiedto addref() andunref() methods but still need to support that behavior.

process.release#

• <Object>

Theprocess.release property returns anObject containing metadata relatedto the current release, including URLs for the source tarball and headers-onlytarball.

process.release contains the following properties:

• name<string> A value that will always be'node'.
• sourceUrl<string> an absolute URL pointing to a.tar.gz file containingthe source code of the current release.
• headersUrl<string> an absolute URL pointing to a.tar.gz file containingonly the source header files for the current release. This file issignificantly smaller than the full source file and can be used for compilingNode.js native add-ons.
• libUrl<string> |<undefined> an absolute URL pointing to anode.lib filematching the architecture and version of the current release. This file isused for compiling Node.js native add-ons.This property is only present onWindows builds of Node.js and will be missing on all other platforms.
• lts<string> |<undefined> a string label identifying theLTS label for thisrelease. This property only exists for LTS releases and isundefined for allother release types, includingCurrent releases. Valid values include theLTS Release code names (including those that are no longer supported).
  • 'Fermium' for the 14.x LTS line beginning with 14.15.0.
  • 'Gallium' for the 16.x LTS line beginning with 16.13.0.
  • 'Hydrogen' for the 18.x LTS line beginning with 18.12.0.For other LTS Release code names, seeNode.js Changelog Archive

{name:'node',lts:'Hydrogen',sourceUrl:'https://nodejs.org/download/release/v18.12.0/node-v18.12.0.tar.gz',headersUrl:'https://nodejs.org/download/release/v18.12.0/node-v18.12.0-headers.tar.gz',libUrl:'https://nodejs.org/download/release/v18.12.0/win-x64/node.lib'}copy

In custom builds from non-release versions of the source tree, only thename property may be present. The additional properties should not berelied upon to exist.

process.report#

• <Object>

process.report is an object whose methods are used to generate diagnosticreports for the current process. Additional documentation is available in thereport documentation.

import { report }from'node:process';console.log(`Reports are compact?${report.compact}`);const { report } =require('node:process');console.log(`Reports are compact?${report.compact}`);copy

import { report }from'node:process';console.log(`Report directory is${report.directory}`);const { report } =require('node:process');console.log(`Report directory is${report.directory}`);copy

import { report }from'node:process';console.log(`Report filename is${report.filename}`);const { report } =require('node:process');console.log(`Report filename is${report.filename}`);copy

import { report }from'node:process';import utilfrom'node:util';const data = report.getReport();console.log(data.header.nodejsVersion);// Similar to process.report.writeReport()import fsfrom'node:fs';fs.writeFileSync('my-report.log', util.inspect(data),'utf8');const { report } =require('node:process');const util =require('node:util');const data = report.getReport();console.log(data.header.nodejsVersion);// Similar to process.report.writeReport()const fs =require('node:fs');fs.writeFileSync('my-report.log', util.inspect(data),'utf8');copy

import { report }from'node:process';console.log(`Report on fatal error:${report.reportOnFatalError}`);const { report } =require('node:process');console.log(`Report on fatal error:${report.reportOnFatalError}`);copy

import { report }from'node:process';console.log(`Report on signal:${report.reportOnSignal}`);const { report } =require('node:process');console.log(`Report on signal:${report.reportOnSignal}`);copy

import { report }from'node:process';console.log(`Report on exception:${report.reportOnUncaughtException}`);const { report } =require('node:process');console.log(`Report on exception:${report.reportOnUncaughtException}`);copy

import { report }from'node:process';console.log(`Report signal:${report.signal}`);const { report } =require('node:process');console.log(`Report signal:${report.signal}`);copy

import { report }from'node:process';report.writeReport();const { report } =require('node:process');report.writeReport();copy

process.resourceUsage()#

• Returns:<Object> the resource usage for the current process. All of thesevalues come from theuv_getrusage call which returnsauv_rusage_t struct.
  • userCPUTime<integer> maps toru_utime computed in microseconds.It is the same value asprocess.cpuUsage().user.
  • systemCPUTime<integer> maps toru_stime computed in microseconds.It is the same value asprocess.cpuUsage().system.
  • maxRSS<integer> maps toru_maxrss which is the maximum resident setsize used in kilobytes.
  • sharedMemorySize<integer> maps toru_ixrss but is not supported byany platform.
  • unsharedDataSize<integer> maps toru_idrss but is not supported byany platform.
  • unsharedStackSize<integer> maps toru_isrss but is not supported byany platform.
  • minorPageFault<integer> maps toru_minflt which is the number ofminor page faults for the process, seethis article for more details.
  • majorPageFault<integer> maps toru_majflt which is the number ofmajor page faults for the process, seethis article for more details. This field is notsupported on Windows.
  • swappedOut<integer> maps toru_nswap but is not supported by anyplatform.
  • fsRead<integer> maps toru_inblock which is the number of times thefile system had to perform input.
  • fsWrite<integer> maps toru_oublock which is the number of times thefile system had to perform output.
  • ipcSent<integer> maps toru_msgsnd but is not supported by anyplatform.
  • ipcReceived<integer> maps toru_msgrcv but is not supported by anyplatform.
  • signalsCount<integer> maps toru_nsignals but is not supported by anyplatform.
  • voluntaryContextSwitches<integer> maps toru_nvcsw which is thenumber of times a CPU context switch resulted due to a process voluntarilygiving up the processor before its time slice was completed (usually toawait availability of a resource). This field is not supported on Windows.
  • involuntaryContextSwitches<integer> maps toru_nivcsw which is thenumber of times a CPU context switch resulted due to a higher priorityprocess becoming runnable or because the current process exceeded itstime slice. This field is not supported on Windows.

import { resourceUsage }from'node:process';console.log(resourceUsage());/*  Will output:  {    userCPUTime: 82872,    systemCPUTime: 4143,    maxRSS: 33164,    sharedMemorySize: 0,    unsharedDataSize: 0,    unsharedStackSize: 0,    minorPageFault: 2469,    majorPageFault: 0,    swappedOut: 0,    fsRead: 0,    fsWrite: 8,    ipcSent: 0,    ipcReceived: 0,    signalsCount: 0,    voluntaryContextSwitches: 79,    involuntaryContextSwitches: 1  }*/const { resourceUsage } =require('node:process');console.log(resourceUsage());/*  Will output:  {    userCPUTime: 82872,    systemCPUTime: 4143,    maxRSS: 33164,    sharedMemorySize: 0,    unsharedDataSize: 0,    unsharedStackSize: 0,    minorPageFault: 2469,    majorPageFault: 0,    swappedOut: 0,    fsRead: 0,    fsWrite: 8,    ipcSent: 0,    ipcReceived: 0,    signalsCount: 0,    voluntaryContextSwitches: 79,    involuntaryContextSwitches: 1  }*/copy

process.send(message[, sendHandle[, options]][, callback])#

• message<Object>
• sendHandle<net.Server> |<net.Socket>
• options<Object> used to parameterize the sending of certain types ofhandles.options supports the following properties:
  • keepOpen<boolean> A value that can be used when passing instances ofnet.Socket. Whentrue, the socket is kept open in the sending process.Default:false.
• callback<Function>
• Returns:<boolean>

If Node.js is spawned with an IPC channel, theprocess.send() method can beused to send messages to the parent process. Messages will be received as a'message' event on the parent'sChildProcess object.

If Node.js was not spawned with an IPC channel,process.send will beundefined.

The message goes through serialization and parsing. The resulting message mightnot be the same as what is originally sent.

process.setegid(id)#

• id<string> |<number> A group name or ID

Theprocess.setegid() method sets the effective group identity of the process.(Seesetegid(2).) Theid can be passed as either a numeric ID or a groupname string. If a group name is specified, this method blocks while resolvingthe associated a numeric ID.

import processfrom'node:process';if (process.getegid && process.setegid) {console.log(`Current gid:${process.getegid()}`);try {    process.setegid(501);console.log(`New gid:${process.getegid()}`);  }catch (err) {console.error(`Failed to set gid:${err}`);  }}const process =require('node:process');if (process.getegid && process.setegid) {console.log(`Current gid:${process.getegid()}`);try {    process.setegid(501);console.log(`New gid:${process.getegid()}`);  }catch (err) {console.error(`Failed to set gid:${err}`);  }}copy

This function is only available on POSIX platforms (i.e. not Windows orAndroid).This feature is not available inWorker threads.

process.seteuid(id)#

• id<string> |<number> A user name or ID

Theprocess.seteuid() method sets the effective user identity of the process.(Seeseteuid(2).) Theid can be passed as either a numeric ID or a usernamestring. If a username is specified, the method blocks while resolving theassociated numeric ID.

import processfrom'node:process';if (process.geteuid && process.seteuid) {console.log(`Current uid:${process.geteuid()}`);try {    process.seteuid(501);console.log(`New uid:${process.geteuid()}`);  }catch (err) {console.error(`Failed to set uid:${err}`);  }}const process =require('node:process');if (process.geteuid && process.seteuid) {console.log(`Current uid:${process.geteuid()}`);try {    process.seteuid(501);console.log(`New uid:${process.geteuid()}`);  }catch (err) {console.error(`Failed to set uid:${err}`);  }}copy

This function is only available on POSIX platforms (i.e. not Windows orAndroid).This feature is not available inWorker threads.

process.setgid(id)#

• id<string> |<number> The group name or ID

Theprocess.setgid() method sets the group identity of the process. (Seesetgid(2).) Theid can be passed as either a numeric ID or a group namestring. If a group name is specified, this method blocks while resolving theassociated numeric ID.

import processfrom'node:process';if (process.getgid && process.setgid) {console.log(`Current gid:${process.getgid()}`);try {    process.setgid(501);console.log(`New gid:${process.getgid()}`);  }catch (err) {console.error(`Failed to set gid:${err}`);  }}const process =require('node:process');if (process.getgid && process.setgid) {console.log(`Current gid:${process.getgid()}`);try {    process.setgid(501);console.log(`New gid:${process.getgid()}`);  }catch (err) {console.error(`Failed to set gid:${err}`);  }}copy

This function is only available on POSIX platforms (i.e. not Windows orAndroid).This feature is not available inWorker threads.

process.setgroups(groups)#

• groups<integer[]>

Theprocess.setgroups() method sets the supplementary group IDs for theNode.js process. This is a privileged operation that requires the Node.jsprocess to haveroot or theCAP_SETGID capability.

Thegroups array can contain numeric group IDs, group names, or both.

import processfrom'node:process';if (process.getgroups && process.setgroups) {try {    process.setgroups([501]);console.log(process.getgroups());// new groups  }catch (err) {console.error(`Failed to set groups:${err}`);  }}const process =require('node:process');if (process.getgroups && process.setgroups) {try {    process.setgroups([501]);console.log(process.getgroups());// new groups  }catch (err) {console.error(`Failed to set groups:${err}`);  }}copy

This function is only available on POSIX platforms (i.e. not Windows orAndroid).This feature is not available inWorker threads.

process.setuid(id)#

• id<integer> |<string>

Theprocess.setuid(id) method sets the user identity of the process. (Seesetuid(2).) Theid can be passed as either a numeric ID or a username string.If a username is specified, the method blocks while resolving the associatednumeric ID.

import processfrom'node:process';if (process.getuid && process.setuid) {console.log(`Current uid:${process.getuid()}`);try {    process.setuid(501);console.log(`New uid:${process.getuid()}`);  }catch (err) {console.error(`Failed to set uid:${err}`);  }}const process =require('node:process');if (process.getuid && process.setuid) {console.log(`Current uid:${process.getuid()}`);try {    process.setuid(501);console.log(`New uid:${process.getuid()}`);  }catch (err) {console.error(`Failed to set uid:${err}`);  }}copy

This function is only available on POSIX platforms (i.e. not Windows orAndroid).This feature is not available inWorker threads.

process.setSourceMapsEnabled(val)#

• val<boolean>

This function enables or disables theSource Map support forstack traces.

It provides same features as launching Node.js process with commandline options--enable-source-maps.

Only source maps in JavaScript files that are loaded after source maps has beenenabled will be parsed and loaded.

This implies callingmodule.setSourceMapsSupport() with an option{ nodeModules: true, generatedCode: true }.

process.setUncaughtExceptionCaptureCallback(fn)#

• fn<Function> |<null>

Theprocess.setUncaughtExceptionCaptureCallback() function sets a functionthat will be invoked when an uncaught exception occurs, which will receive theexception value itself as its first argument.

If such a function is set, the'uncaughtException' event willnot be emitted. If--abort-on-uncaught-exception was passed from thecommand line or set throughv8.setFlagsFromString(), the process willnot abort. Actions configured to take place on exceptions such as reportgenerations will be affected too

To unset the capture function,process.setUncaughtExceptionCaptureCallback(null) may be used. Calling thismethod with a non-null argument while another capture function is set willthrow an error.

Using this function is mutually exclusive with using the deprecateddomain built-in module.

process.sourceMapsEnabled#

• <boolean>

Theprocess.sourceMapsEnabled property returns whether theSource Map support for stack traces is enabled.

process.stderr#

• <Stream>

Theprocess.stderr property returns a stream connected tostderr (fd2). It is anet.Socket (which is aDuplexstream) unless fd2 refers to a file, in which case it isaWritable stream.

process.stderr differs from other Node.js streams in important ways. Seenote on process I/O for more information.

process.stdin#

• <Stream>

Theprocess.stdin property returns a stream connected tostdin (fd0). It is anet.Socket (which is aDuplexstream) unless fd0 refers to a file, in which case it isaReadable stream.

For details of how to read fromstdin seereadable.read().

As aDuplex stream,process.stdin can also be used in "old" mode thatis compatible with scripts written for Node.js prior to v0.10.For more information seeStream compatibility.

In "old" streams mode thestdin stream is paused by default, so onemust callprocess.stdin.resume() to read from it. Note also that callingprocess.stdin.resume() itself would switch stream to "old" mode.

process.stdout#

• <Stream>

Theprocess.stdout property returns a stream connected tostdout (fd1). It is anet.Socket (which is aDuplexstream) unless fd1 refers to a file, in which case it isaWritable stream.

For example, to copyprocess.stdin toprocess.stdout:

import { stdin, stdout }from'node:process';stdin.pipe(stdout);const { stdin, stdout } =require('node:process');stdin.pipe(stdout);copy

process.stdout differs from other Node.js streams in important ways. Seenote on process I/O for more information.

$node -p"Boolean(process.stdin.isTTY)"true$echo"foo" | node -p"Boolean(process.stdin.isTTY)"false$node -p"Boolean(process.stdout.isTTY)"true$node -p"Boolean(process.stdout.isTTY)" |catfalsecopy

process.throwDeprecation#

• <boolean>

The initial value ofprocess.throwDeprecation indicates whether the--throw-deprecation flag is set on the current Node.js process.process.throwDeprecation is mutable, so whether or not deprecationwarnings result in errors may be altered at runtime. See thedocumentation for the'warning' event and theemitWarning() method for more information.

$node --throw-deprecation -p"process.throwDeprecation"true$node -p"process.throwDeprecation"undefined$node>process.emitWarning('test','DeprecationWarning');undefined>(node:26598) DeprecationWarning:test>process.throwDeprecation =true;true>process.emitWarning('test','DeprecationWarning');Thrown:[DeprecationWarning: test] { name: 'DeprecationWarning' }copy

process.threadCpuUsage([previousValue])#

• previousValue<Object> A previous return value from callingprocess.threadCpuUsage()
• Returns:<Object>
  • user<integer>
  • system<integer>

Theprocess.threadCpuUsage() method returns the user and system CPU time usage ofthe current worker thread, in an object with propertiesuser andsystem, whosevalues are microsecond values (millionth of a second).

The result of a previous call toprocess.threadCpuUsage() can be passed as theargument to the function, to get a diff reading.

process.title#

• <string>

Theprocess.title property returns the current process title (i.e. returnsthe current value ofps). Assigning a new value toprocess.title modifiesthe current value ofps.

When a new value is assigned, different platforms will impose different maximumlength restrictions on the title. Usually such restrictions are quite limited.For instance, on Linux and macOS,process.title is limited to the size of thebinary name plus the length of the command-line arguments because setting theprocess.title overwrites theargv memory of the process. Node.js v0.8allowed for longer process title strings by also overwriting theenvironmemory but that was potentially insecure and confusing in some (rather obscure)cases.

Assigning a value toprocess.title might not result in an accurate labelwithin process manager applications such as macOS Activity Monitor or WindowsServices Manager.

process.traceDeprecation#

• <boolean>

Theprocess.traceDeprecation property indicates whether the--trace-deprecation flag is set on the current Node.js process. See thedocumentation for the'warning' event and theemitWarning() method for more information about thisflag's behavior.

process.umask()#

process.umask() returns the Node.js process's file mode creation mask. Childprocesses inherit the mask from the parent process.

process.umask(mask)#

• mask<string> |<integer>

process.umask(mask) sets the Node.js process's file mode creation mask. Childprocesses inherit the mask from the parent process. Returns the previous mask.

import { umask }from'node:process';const newmask =0o022;const oldmask =umask(newmask);console.log(`Changed umask from${oldmask.toString(8)} to${newmask.toString(8)}`,);const { umask } =require('node:process');const newmask =0o022;const oldmask =umask(newmask);console.log(`Changed umask from${oldmask.toString(8)} to${newmask.toString(8)}`,);copy

InWorker threads,process.umask(mask) will throw an exception.

process.unref(maybeRefable)#

• maybeUnfefable<any> An object that may be "unref'd".

An object is "unrefable" if it implements the Node.js "Refable protocol".Specifically, this means that the object implements theSymbol.for('nodejs.ref')andSymbol.for('nodejs.unref') methods. "Ref'd" objects will keep the Node.jsevent loop alive, while "unref'd" objects will not. Historically, this wasimplemented by usingref() andunref() methods directly on the objects.This pattern, however, is being deprecated in favor of the "Refable protocol"in order to better support Web Platform API types whose APIs cannot be modifiedto addref() andunref() methods but still need to support that behavior.

process.uptime()#

• Returns:<number>

Theprocess.uptime() method returns the number of seconds the current Node.jsprocess has been running.

The return value includes fractions of a second. UseMath.floor() to get wholeseconds.

process.version#

• <string>

Theprocess.version property contains the Node.js version string.

import { version }from'node:process';console.log(`Version:${version}`);// Version: v14.8.0const { version } =require('node:process');console.log(`Version:${version}`);// Version: v14.8.0copy

To get the version string without the prependedv, useprocess.versions.node.

process.versions#

• <Object>

Theprocess.versions property returns an object listing the version strings ofNode.js and its dependencies.process.versions.modules indicates the currentABI version, which is increased whenever a C++ API changes. Node.js will refuseto load modules that were compiled against a different module ABI version.

import { versions }from'node:process';console.log(versions);const { versions } =require('node:process');console.log(versions);copy

Will generate an object similar to:

{ node: '23.0.0',  acorn: '8.11.3',  ada: '2.7.8',  ares: '1.28.1',  base64: '0.5.2',  brotli: '1.1.0',  cjs_module_lexer: '1.2.2',  cldr: '45.0',  icu: '75.1',  llhttp: '9.2.1',  modules: '127',  napi: '9',  nghttp2: '1.61.0',  nghttp3: '0.7.0',  ngtcp2: '1.3.0',  openssl: '3.0.13+quic',  simdjson: '3.8.0',  simdutf: '5.2.4',  sqlite: '3.46.0',  tz: '2024a',  undici: '6.13.0',  unicode: '15.1',  uv: '1.48.0',  uvwasi: '0.0.20',  v8: '12.4.254.14-node.11',  zlib: '1.3.0.1-motley-7d77fb7' }copy

Exit codes#

Node.js will normally exit with a0 status code when no more asyncoperations are pending. The following status codes are used in othercases:

• 1Uncaught Fatal Exception: There was an uncaught exception,and it was not handled by a domain or an'uncaughtException' eventhandler.
• 2: Unused (reserved by Bash for builtin misuse)
• 3Internal JavaScript Parse Error: The JavaScript source codeinternal in the Node.js bootstrapping process caused a parse error. Thisis extremely rare, and generally can only happen during developmentof Node.js itself.
• 4Internal JavaScript Evaluation Failure: The JavaScriptsource code internal in the Node.js bootstrapping process failed toreturn a function value when evaluated. This is extremely rare, andgenerally can only happen during development of Node.js itself.
• 5Fatal Error: There was a fatal unrecoverable error in V8.Typically a message will be printed to stderr with the prefixFATAL ERROR.
• 6Non-function Internal Exception Handler: There was anuncaught exception, but the internal fatal exception handlerfunction was somehow set to a non-function, and could not be called.
• 7Internal Exception Handler Run-Time Failure: There was anuncaught exception, and the internal fatal exception handlerfunction itself threw an error while attempting to handle it. Thiscan happen, for example, if an'uncaughtException' ordomain.on('error') handler throws an error.
• 8: Unused. In previous versions of Node.js, exit code 8 sometimesindicated an uncaught exception.
• 9Invalid Argument: Either an unknown option was specified,or an option requiring a value was provided without a value.
• 10Internal JavaScript Run-Time Failure: The JavaScriptsource code internal in the Node.js bootstrapping process threw an errorwhen the bootstrapping function was called. This is extremely rare,and generally can only happen during development of Node.js itself.
• 12Invalid Debug Argument: The--inspect and/or--inspect-brkoptions were set, but the port number chosen was invalid or unavailable.
• 13Unsettled Top-Level Await:await was used outside of a functionin the top-level code, but the passedPromise never settled.
• 14Snapshot Failure: Node.js was started to build a V8 startupsnapshot and it failed because certain requirements of the state ofthe application were not met.
• >128Signal Exits: If Node.js receives a fatal signal such asSIGKILL orSIGHUP, then its exit code will be128 plus thevalue of the signal code. This is a standard POSIX practice, sinceexit codes are defined to be 7-bit integers, and signal exits setthe high-order bit, and then contain the value of the signal code.For example, signalSIGABRT has value6, so the expected exitcode will be128 +6, or134.