Spawning.bat and.cmd files on Windows#

The importance of the distinction betweenchild_process.exec() andchild_process.execFile() can vary based on platform. On Unix-typeoperating systems (Unix, Linux, macOS)child_process.execFile() can bemore efficient because it does not spawn a shell by default. On Windows,however,.bat and.cmd files are not executable on their own without aterminal, and therefore cannot be launched usingchild_process.execFile().When running on Windows,.bat and.cmd files can be invoked usingchild_process.spawn() with theshell option set, withchild_process.exec(), or by spawningcmd.exe and passing the.bat or.cmd file as an argument (which is what theshell option andchild_process.exec() do). In any case, if the script filename containsspaces it needs to be quoted.

// OR...const { exec, spawn } =require('node:child_process');exec('my.bat',(err, stdout, stderr) => {if (err) {console.error(err);return;  }console.log(stdout);});// Script with spaces in the filename:const bat =spawn('"my script.cmd" a b', {shell:true });// or:exec('"my script.cmd" a b',(err, stdout, stderr) => {// ...});// OR...import { exec, spawn }from'node:child_process';exec('my.bat',(err, stdout, stderr) => {if (err) {console.error(err);return;  }console.log(stdout);});// Script with spaces in the filename:const bat =spawn('"my script.cmd" a b', {shell:true });// or:exec('"my script.cmd" a b',(err, stdout, stderr) => {// ...});copy

child_process.exec(command[, options][, callback])#

• command<string> The command to run, with space-separated arguments.
• options<Object>
  • cwd<string> |<URL> Current working directory of the child process.Default:process.cwd().
  • env<Object> Environment key-value pairs.Default:process.env.
  • encoding<string>Default:'utf8'
  • shell<string> Shell to execute the command with. SeeShell requirements andDefault Windows shell.Default:'/bin/sh' on Unix,process.env.ComSpec on Windows.
  • signal<AbortSignal> allows aborting the child process using anAbortSignal.
  • timeout<number>Default:0
  • maxBuffer<number> Largest amount of data in bytes allowed on stdout orstderr. If exceeded, the child process is terminated and any output istruncated. See caveat atmaxBuffer and Unicode.Default:1024 * 1024.
  • killSignal<string> |<integer>Default:'SIGTERM'
  • uid<number> Sets the user identity of the process (seesetuid(2)).
  • gid<number> Sets the group identity of the process (seesetgid(2)).
  • windowsHide<boolean> Hide the subprocess console window that wouldnormally be created on Windows systems.Default:false.
• callback<Function> called with the output when process terminates.
  • error<Error>
  • stdout<string> |<Buffer>
  • stderr<string> |<Buffer>
• Returns:<ChildProcess>

Spawns a shell then executes thecommand within that shell, buffering anygenerated output. Thecommand string passed to the exec function is processeddirectly by the shell and special characters (vary based onshell)need to be dealt with accordingly:

const { exec } =require('node:child_process');exec('"/path/to/test file/test.sh" arg1 arg2');// Double quotes are used so that the space in the path is not interpreted as// a delimiter of multiple arguments.exec('echo "The \\$HOME variable is $HOME"');// The $HOME variable is escaped in the first instance, but not in the second.import { exec }from'node:child_process';exec('"/path/to/test file/test.sh" arg1 arg2');// Double quotes are used so that the space in the path is not interpreted as// a delimiter of multiple arguments.exec('echo "The \\$HOME variable is $HOME"');// The $HOME variable is escaped in the first instance, but not in the second.copy

Never pass unsanitized user input to this function. Any input containing shellmetacharacters may be used to trigger arbitrary command execution.

If acallback function is provided, it is called with the arguments(error, stdout, stderr). On success,error will benull. On error,error will be an instance ofError. Theerror.code property will bethe exit code of the process. By convention, any exit code other than0indicates an error.error.signal will be the signal that terminated theprocess.

Thestdout andstderr arguments passed to the callback will contain thestdout and stderr output of the child process. By default, Node.js will decodethe output as UTF-8 and pass strings to the callback. Theencoding optioncan be used to specify the character encoding used to decode the stdout andstderr output. Ifencoding is'buffer', or an unrecognized characterencoding,Buffer objects will be passed to the callback instead.

const { exec } =require('node:child_process');exec('cat *.js missing_file | wc -l',(error, stdout, stderr) => {if (error) {console.error(`exec error:${error}`);return;  }console.log(`stdout:${stdout}`);console.error(`stderr:${stderr}`);});import { exec }from'node:child_process';exec('cat *.js missing_file | wc -l',(error, stdout, stderr) => {if (error) {console.error(`exec error:${error}`);return;  }console.log(`stdout:${stdout}`);console.error(`stderr:${stderr}`);});copy

Iftimeout is greater than0, the parent process will send the signalidentified by thekillSignal property (the default is'SIGTERM') if thechild process runs longer thantimeout milliseconds.

Unlike theexec(3) POSIX system call,child_process.exec() does not replacethe existing process and uses a shell to execute the command.

If this method is invoked as itsutil.promisify()ed version, it returnsaPromise for anObject withstdout andstderr properties. The returnedChildProcess instance is attached to thePromise as achild property. Incase of an error (including any error resulting in an exit code other than 0), arejected promise is returned, with the sameerror object given in thecallback, but with two additional propertiesstdout andstderr.

const util =require('node:util');const exec = util.promisify(require('node:child_process').exec);asyncfunctionlsExample() {const { stdout, stderr } =awaitexec('ls');console.log('stdout:', stdout);console.error('stderr:', stderr);}lsExample();import { promisify }from'node:util';import child_processfrom'node:child_process';const exec =promisify(child_process.exec);asyncfunctionlsExample() {const { stdout, stderr } =awaitexec('ls');console.log('stdout:', stdout);console.error('stderr:', stderr);}lsExample();copy

If thesignal option is enabled, calling.abort() on the correspondingAbortController is similar to calling.kill() on the child process exceptthe error passed to the callback will be anAbortError:

const { exec } =require('node:child_process');const controller =newAbortController();const { signal } = controller;const child =exec('grep ssh', { signal },(error) => {console.error(error);// an AbortError});controller.abort();import { exec }from'node:child_process';const controller =newAbortController();const { signal } = controller;const child =exec('grep ssh', { signal },(error) => {console.error(error);// an AbortError});controller.abort();copy

child_process.execFile(file[, args][, options][, callback])#

• file<string> The name or path of the executable file to run.
• args<string[]> List of string arguments.
• options<Object>
  • cwd<string> |<URL> Current working directory of the child process.
  • env<Object> Environment key-value pairs.Default:process.env.
  • encoding<string>Default:'utf8'
  • timeout<number>Default:0
  • maxBuffer<number> Largest amount of data in bytes allowed on stdout orstderr. If exceeded, the child process is terminated and any output istruncated. See caveat atmaxBuffer and Unicode.Default:1024 * 1024.
  • killSignal<string> |<integer>Default:'SIGTERM'
  • uid<number> Sets the user identity of the process (seesetuid(2)).
  • gid<number> Sets the group identity of the process (seesetgid(2)).
  • windowsHide<boolean> Hide the subprocess console window that wouldnormally be created on Windows systems.Default:false.
  • windowsVerbatimArguments<boolean> No quoting or escaping of arguments isdone on Windows. Ignored on Unix.Default:false.
  • shell<boolean> |<string> Iftrue, runscommand inside of a shell. Uses'/bin/sh' on Unix, andprocess.env.ComSpec on Windows. A differentshell can be specified as a string. SeeShell requirements andDefault Windows shell.Default:false (no shell).
  • signal<AbortSignal> allows aborting the child process using anAbortSignal.
• callback<Function> Called with the output when process terminates.
  • error<Error>
  • stdout<string> |<Buffer>
  • stderr<string> |<Buffer>
• Returns:<ChildProcess>

Thechild_process.execFile() function is similar tochild_process.exec()except that it does not spawn a shell by default. Rather, the specifiedexecutablefile is spawned directly as a new process making it slightly moreefficient thanchild_process.exec().

The same options aschild_process.exec() are supported. Since a shell isnot spawned, behaviors such as I/O redirection and file globbing are notsupported.

const { execFile } =require('node:child_process');const child =execFile('node', ['--version'],(error, stdout, stderr) => {if (error) {throw error;  }console.log(stdout);});import { execFile }from'node:child_process';const child =execFile('node', ['--version'],(error, stdout, stderr) => {if (error) {throw error;  }console.log(stdout);});copy

Thestdout andstderr arguments passed to the callback will contain thestdout and stderr output of the child process. By default, Node.js will decodethe output as UTF-8 and pass strings to the callback. Theencoding optioncan be used to specify the character encoding used to decode the stdout andstderr output. Ifencoding is'buffer', or an unrecognized characterencoding,Buffer objects will be passed to the callback instead.

If this method is invoked as itsutil.promisify()ed version, it returnsaPromise for anObject withstdout andstderr properties. The returnedChildProcess instance is attached to thePromise as achild property. Incase of an error (including any error resulting in an exit code other than 0), arejected promise is returned, with the sameerror object given in thecallback, but with two additional propertiesstdout andstderr.

const util =require('node:util');const execFile = util.promisify(require('node:child_process').execFile);asyncfunctiongetVersion() {const { stdout } =awaitexecFile('node', ['--version']);console.log(stdout);}getVersion();import { promisify }from'node:util';import child_processfrom'node:child_process';const execFile =promisify(child_process.execFile);asyncfunctiongetVersion() {const { stdout } =awaitexecFile('node', ['--version']);console.log(stdout);}getVersion();copy

If theshell option is enabled, do not pass unsanitized user input to thisfunction. Any input containing shell metacharacters may be used to triggerarbitrary command execution.

If thesignal option is enabled, calling.abort() on the correspondingAbortController is similar to calling.kill() on the child process exceptthe error passed to the callback will be anAbortError:

const { execFile } =require('node:child_process');const controller =newAbortController();const { signal } = controller;const child =execFile('node', ['--version'], { signal },(error) => {console.error(error);// an AbortError});controller.abort();import { execFile }from'node:child_process';const controller =newAbortController();const { signal } = controller;const child =execFile('node', ['--version'], { signal },(error) => {console.error(error);// an AbortError});controller.abort();copy

child_process.fork(modulePath[, args][, options])#

• modulePath<string> |<URL> The module to run in the child.
• args<string[]> List of string arguments.
• options<Object>
  • cwd<string> |<URL> Current working directory of the child process.
  • detached<boolean> Prepare child process to run independently of itsparent process. Specific behavior depends on the platform (seeoptions.detached).
  • env<Object> Environment key-value pairs.Default:process.env.
  • execPath<string> Executable used to create the child process.
  • execArgv<string[]> List of string arguments passed to the executable.Default:process.execArgv.
  • gid<number> Sets the group identity of the process (seesetgid(2)).
  • serialization<string> Specify the kind of serialization used for sendingmessages between processes. Possible values are'json' and'advanced'.SeeAdvanced serialization for more details.Default:'json'.
  • signal<AbortSignal> Allows closing the child process using anAbortSignal.
  • killSignal<string> |<integer> The signal value to be used when the spawnedprocess will be killed by timeout or abort signal.Default:'SIGTERM'.
  • silent<boolean> Iftrue, stdin, stdout, and stderr of the childprocess will be piped to the parent process, otherwise they will be inheritedfrom the parent process, see the'pipe' and'inherit' options forchild_process.spawn()'sstdio for more details.Default:false.
  • stdio<Array> |<string> Seechild_process.spawn()'sstdio.When this option is provided, it overridessilent. If the array variantis used, it must contain exactly one item with value'ipc' or an errorwill be thrown. For instance[0, 1, 2, 'ipc'].
  • uid<number> Sets the user identity of the process (seesetuid(2)).
  • windowsVerbatimArguments<boolean> No quoting or escaping of arguments isdone on Windows. Ignored on Unix.Default:false.
  • timeout<number> In milliseconds the maximum amount of time the processis allowed to run.Default:undefined.
• Returns:<ChildProcess>

Thechild_process.fork() method is a special case ofchild_process.spawn() used specifically to spawn new Node.js processes.Likechild_process.spawn(), aChildProcess object is returned. ThereturnedChildProcess will have an additional communication channelbuilt-in that allows messages to be passed back and forth between the parent andchild. Seesubprocess.send() for details.

Keep in mind that spawned Node.js child processes areindependent of the parent with exception of the IPC communication channelthat is established between the two. Each process has its own memory, withtheir own V8 instances. Because of the additional resource allocationsrequired, spawning a large number of child Node.js processes is notrecommended.

By default,child_process.fork() will spawn new Node.js instances using theprocess.execPath of the parent process. TheexecPath property in theoptions object allows for an alternative execution path to be used.

Node.js processes launched with a customexecPath will communicate with theparent process using the file descriptor (fd) identified using theenvironment variableNODE_CHANNEL_FD on the child process.

Unlike thefork(2) POSIX system call,child_process.fork() does not clone thecurrent process.

Theshell option available inchild_process.spawn() is not supported bychild_process.fork() and will be ignored if set.

If thesignal option is enabled, calling.abort() on the correspondingAbortController is similar to calling.kill() on the child process exceptthe error passed to the callback will be anAbortError:

const { fork } =require('node:child_process');const process =require('node:process');if (process.argv[2] ==='child') {setTimeout(() => {console.log(`Hello from${process.argv[2]}!`);  },1_000);}else {const controller =newAbortController();const { signal } = controller;const child =fork(__filename, ['child'], { signal });  child.on('error',(err) => {// This will be called with err being an AbortError if the controller aborts  });  controller.abort();// Stops the child process}import { fork }from'node:child_process';import processfrom'node:process';if (process.argv[2] ==='child') {setTimeout(() => {console.log(`Hello from${process.argv[2]}!`);  },1_000);}else {const controller =newAbortController();const { signal } = controller;const child =fork(import.meta.url, ['child'], { signal });  child.on('error',(err) => {// This will be called with err being an AbortError if the controller aborts  });  controller.abort();// Stops the child process}copy

child_process.spawn(command[, args][, options])#

• command<string> The command to run.
• args<string[]> List of string arguments.
• options<Object>
  • cwd<string> |<URL> Current working directory of the child process.
  • env<Object> Environment key-value pairs.Default:process.env.
  • argv0<string> Explicitly set the value ofargv[0] sent to the childprocess. This will be set tocommand if not specified.
  • stdio<Array> |<string> Child's stdio configuration (seeoptions.stdio).
  • detached<boolean> Prepare child process to run independently ofits parent process. Specific behavior depends on the platform (seeoptions.detached).
  • uid<number> Sets the user identity of the process (seesetuid(2)).
  • gid<number> Sets the group identity of the process (seesetgid(2)).
  • serialization<string> Specify the kind of serialization used for sendingmessages between processes. Possible values are'json' and'advanced'.SeeAdvanced serialization for more details.Default:'json'.
  • shell<boolean> |<string> Iftrue, runscommand inside of a shell. Uses'/bin/sh' on Unix, andprocess.env.ComSpec on Windows. A differentshell can be specified as a string. SeeShell requirements andDefault Windows shell.Default:false (no shell).
  • windowsVerbatimArguments<boolean> No quoting or escaping of arguments isdone on Windows. Ignored on Unix. This is set totrue automaticallywhenshell is specified and is CMD.Default:false.
  • windowsHide<boolean> Hide the subprocess console window that wouldnormally be created on Windows systems.Default:false.
  • signal<AbortSignal> allows aborting the child process using anAbortSignal.
  • timeout<number> In milliseconds the maximum amount of time the processis allowed to run.Default:undefined.
  • killSignal<string> |<integer> The signal value to be used when the spawnedprocess will be killed by timeout or abort signal.Default:'SIGTERM'.
• Returns:<ChildProcess>

Thechild_process.spawn() method spawns a new process using the givencommand, with command-line arguments inargs. If omitted,args defaultsto an empty array.

If theshell option is enabled, do not pass unsanitized user input to thisfunction. Any input containing shell metacharacters may be used to triggerarbitrary command execution.

A third argument may be used to specify additional options, with these defaults:

const defaults = {cwd:undefined,env: process.env,};copy

Usecwd to specify the working directory from which the process is spawned.If not given, the default is to inherit the current working directory. If given,but the path does not exist, the child process emits anENOENT errorand exits immediately.ENOENT is also emitted when the commanddoes not exist.

Useenv to specify environment variables that will be visible to the newprocess, the default isprocess.env.

undefined values inenv will be ignored.

Example of runningls -lh /usr, capturingstdout,stderr, and theexit code:

const { spawn } =require('node:child_process');const ls =spawn('ls', ['-lh','/usr']);ls.stdout.on('data',(data) => {console.log(`stdout:${data}`);});ls.stderr.on('data',(data) => {console.error(`stderr:${data}`);});ls.on('close',(code) => {console.log(`child process exited with code${code}`);});import { spawn }from'node:child_process';const ls =spawn('ls', ['-lh','/usr']);ls.stdout.on('data',(data) => {console.log(`stdout:${data}`);});ls.stderr.on('data',(data) => {console.error(`stderr:${data}`);});ls.on('close',(code) => {console.log(`child process exited with code${code}`);});copy

Example: A very elaborate way to runps ax | grep ssh

const { spawn } =require('node:child_process');const ps =spawn('ps', ['ax']);const grep =spawn('grep', ['ssh']);ps.stdout.on('data',(data) => {  grep.stdin.write(data);});ps.stderr.on('data',(data) => {console.error(`ps stderr:${data}`);});ps.on('close',(code) => {if (code !==0) {console.log(`ps process exited with code${code}`);  }  grep.stdin.end();});grep.stdout.on('data',(data) => {console.log(data.toString());});grep.stderr.on('data',(data) => {console.error(`grep stderr:${data}`);});grep.on('close',(code) => {if (code !==0) {console.log(`grep process exited with code${code}`);  }});import { spawn }from'node:child_process';const ps =spawn('ps', ['ax']);const grep =spawn('grep', ['ssh']);ps.stdout.on('data',(data) => {  grep.stdin.write(data);});ps.stderr.on('data',(data) => {console.error(`ps stderr:${data}`);});ps.on('close',(code) => {if (code !==0) {console.log(`ps process exited with code${code}`);  }  grep.stdin.end();});grep.stdout.on('data',(data) => {console.log(data.toString());});grep.stderr.on('data',(data) => {console.error(`grep stderr:${data}`);});grep.on('close',(code) => {if (code !==0) {console.log(`grep process exited with code${code}`);  }});copy

Example of checking for failedspawn:

const { spawn } =require('node:child_process');const subprocess =spawn('bad_command');subprocess.on('error',(err) => {console.error('Failed to start subprocess.');});import { spawn }from'node:child_process';const subprocess =spawn('bad_command');subprocess.on('error',(err) => {console.error('Failed to start subprocess.');});copy

Certain platforms (macOS, Linux) will use the value ofargv[0] for the processtitle while others (Windows, SunOS) will usecommand.

Node.js overwritesargv[0] withprocess.execPath on startup, soprocess.argv[0] in a Node.js child process will not match theargv0parameter passed tospawn from the parent. Retrieve it with theprocess.argv0 property instead.

If thesignal option is enabled, calling.abort() on the correspondingAbortController is similar to calling.kill() on the child process exceptthe error passed to the callback will be anAbortError:

const { spawn } =require('node:child_process');const controller =newAbortController();const { signal } = controller;const grep =spawn('grep', ['ssh'], { signal });grep.on('error',(err) => {// This will be called with err being an AbortError if the controller aborts});controller.abort();// Stops the child processimport { spawn }from'node:child_process';const controller =newAbortController();const { signal } = controller;const grep =spawn('grep', ['ssh'], { signal });grep.on('error',(err) => {// This will be called with err being an AbortError if the controller aborts});controller.abort();// Stops the child processcopy

const { spawn } =require('node:child_process');const process =require('node:process');const subprocess =spawn(process.argv[0], ['child_program.js'], {detached:true,stdio:'ignore',});subprocess.unref();import { spawn }from'node:child_process';import processfrom'node:process';const subprocess =spawn(process.argv[0], ['child_program.js'], {detached:true,stdio:'ignore',});subprocess.unref();copy

const { openSync } =require('node:fs');const { spawn } =require('node:child_process');const out =openSync('./out.log','a');const err =openSync('./out.log','a');const subprocess =spawn('prg', [], {detached:true,stdio: ['ignore', out, err ],});subprocess.unref();import { openSync }from'node:fs';import { spawn }from'node:child_process';const out =openSync('./out.log','a');const err =openSync('./out.log','a');const subprocess =spawn('prg', [], {detached:true,stdio: ['ignore', out, err ],});subprocess.unref();copy

const { spawn } =require('node:child_process');const process =require('node:process');// Child will use parent's stdios.spawn('prg', [], {stdio:'inherit' });// Spawn child sharing only stderr.spawn('prg', [], {stdio: ['pipe','pipe', process.stderr] });// Open an extra fd=4, to interact with programs presenting a// startd-style interface.spawn('prg', [], {stdio: ['pipe',null,null,null,'pipe'] });import { spawn }from'node:child_process';import processfrom'node:process';// Child will use parent's stdios.spawn('prg', [], {stdio:'inherit' });// Spawn child sharing only stderr.spawn('prg', [], {stdio: ['pipe','pipe', process.stderr] });// Open an extra fd=4, to interact with programs presenting a// startd-style interface.spawn('prg', [], {stdio: ['pipe',null,null,null,'pipe'] });copy

child_process.execFileSync(file[, args][, options])#

• file<string> The name or path of the executable file to run.
• args<string[]> List of string arguments.
• options<Object>
  • cwd<string> |<URL> Current working directory of the child process.
  • input<string> |<Buffer> |<TypedArray> |<DataView> The value which will be passedas stdin to the spawned process. Ifstdio[0] is set to'pipe', Supplyingthis value will overridestdio[0].
  • stdio<string> |<Array> Child's stdio configuration.Seechild_process.spawn()'sstdio.stderr by default willbe output to the parent process' stderr unlessstdio is specified.Default:'pipe'.
  • env<Object> Environment key-value pairs.Default:process.env.
  • uid<number> Sets the user identity of the process (seesetuid(2)).
  • gid<number> Sets the group identity of the process (seesetgid(2)).
  • timeout<number> In milliseconds the maximum amount of time the processis allowed to run.Default:undefined.
  • killSignal<string> |<integer> The signal value to be used when the spawnedprocess will be killed.Default:'SIGTERM'.
  • maxBuffer<number> Largest amount of data in bytes allowed on stdout orstderr. If exceeded, the child process is terminated. See caveat atmaxBuffer and Unicode.Default:1024 * 1024.
  • encoding<string> The encoding used for all stdio inputs and outputs.Default:'buffer'.
  • windowsHide<boolean> Hide the subprocess console window that wouldnormally be created on Windows systems.Default:false.
  • shell<boolean> |<string> Iftrue, runscommand inside of a shell. Uses'/bin/sh' on Unix, andprocess.env.ComSpec on Windows. A differentshell can be specified as a string. SeeShell requirements andDefault Windows shell.Default:false (no shell).
• Returns:<Buffer> |<string> The stdout from the command.

Thechild_process.execFileSync() method is generally identical tochild_process.execFile() with the exception that the method will notreturn until the child process has fully closed. When a timeout has beenencountered andkillSignal is sent, the method won't return until the processhas completely exited.

If the child process intercepts and handles theSIGTERM signal anddoes not exit, the parent process will still wait until the child process hasexited.

If the process times out or has a non-zero exit code, this method will throw anError that will include the full result of the underlyingchild_process.spawnSync().

If theshell option is enabled, do not pass unsanitized user input to thisfunction. Any input containing shell metacharacters may be used to triggerarbitrary command execution.

const { execFileSync } =require('node:child_process');try {const stdout =execFileSync('my-script.sh', ['my-arg'], {// Capture stdout and stderr from child process. Overrides the// default behavior of streaming child stderr to the parent stderrstdio:'pipe',// Use utf8 encoding for stdio pipesencoding:'utf8',  });console.log(stdout);}catch (err) {if (err.code) {// Spawning child process failedconsole.error(err.code);  }else {// Child was spawned but exited with non-zero exit code// Error contains any stdout and stderr from the childconst { stdout, stderr } = err;console.error({ stdout, stderr });  }}import { execFileSync }from'node:child_process';try {const stdout =execFileSync('my-script.sh', ['my-arg'], {// Capture stdout and stderr from child process. Overrides the// default behavior of streaming child stderr to the parent stderrstdio:'pipe',// Use utf8 encoding for stdio pipesencoding:'utf8',  });console.log(stdout);}catch (err) {if (err.code) {// Spawning child process failedconsole.error(err.code);  }else {// Child was spawned but exited with non-zero exit code// Error contains any stdout and stderr from the childconst { stdout, stderr } = err;console.error({ stdout, stderr });  }}copy

child_process.execSync(command[, options])#

• command<string> The command to run.
• options<Object>
  • cwd<string> |<URL> Current working directory of the child process.
  • input<string> |<Buffer> |<TypedArray> |<DataView> The value which will be passedas stdin to the spawned process. Ifstdio[0] is set to'pipe', Supplyingthis value will overridestdio[0].
  • stdio<string> |<Array> Child's stdio configuration.Seechild_process.spawn()'sstdio.stderr by default willbe output to the parent process' stderr unlessstdio is specified.Default:'pipe'.
  • env<Object> Environment key-value pairs.Default:process.env.
  • shell<string> Shell to execute the command with. SeeShell requirements andDefault Windows shell.Default:'/bin/sh' on Unix,process.env.ComSpec on Windows.
  • uid<number> Sets the user identity of the process. (Seesetuid(2)).
  • gid<number> Sets the group identity of the process. (Seesetgid(2)).
  • timeout<number> In milliseconds the maximum amount of time the processis allowed to run.Default:undefined.
  • killSignal<string> |<integer> The signal value to be used when the spawnedprocess will be killed.Default:'SIGTERM'.
  • maxBuffer<number> Largest amount of data in bytes allowed on stdout orstderr. If exceeded, the child process is terminated and any output istruncated. See caveat atmaxBuffer and Unicode.Default:1024 * 1024.
  • encoding<string> The encoding used for all stdio inputs and outputs.Default:'buffer'.
  • windowsHide<boolean> Hide the subprocess console window that wouldnormally be created on Windows systems.Default:false.
• Returns:<Buffer> |<string> The stdout from the command.

Thechild_process.execSync() method is generally identical tochild_process.exec() with the exception that the method will not returnuntil the child process has fully closed. When a timeout has been encounteredandkillSignal is sent, the method won't return until the process hascompletely exited. If the child process intercepts and handles theSIGTERMsignal and doesn't exit, the parent process will wait until the child processhas exited.

If the process times out or has a non-zero exit code, this method will throw.TheError object will contain the entire result fromchild_process.spawnSync().

Never pass unsanitized user input to this function. Any input containing shellmetacharacters may be used to trigger arbitrary command execution.

child_process.spawnSync(command[, args][, options])#

• command<string> The command to run.
• args<string[]> List of string arguments.
• options<Object>
  • cwd<string> |<URL> Current working directory of the child process.
  • input<string> |<Buffer> |<TypedArray> |<DataView> The value which will be passedas stdin to the spawned process. Ifstdio[0] is set to'pipe', Supplyingthis value will overridestdio[0].
  • argv0<string> Explicitly set the value ofargv[0] sent to the childprocess. This will be set tocommand if not specified.
  • stdio<string> |<Array> Child's stdio configuration.Seechild_process.spawn()'sstdio.Default:'pipe'.
  • env<Object> Environment key-value pairs.Default:process.env.
  • uid<number> Sets the user identity of the process (seesetuid(2)).
  • gid<number> Sets the group identity of the process (seesetgid(2)).
  • timeout<number> In milliseconds the maximum amount of time the processis allowed to run.Default:undefined.
  • killSignal<string> |<integer> The signal value to be used when the spawnedprocess will be killed.Default:'SIGTERM'.
  • maxBuffer<number> Largest amount of data in bytes allowed on stdout orstderr. If exceeded, the child process is terminated and any output istruncated. See caveat atmaxBuffer and Unicode.Default:1024 * 1024.
  • encoding<string> The encoding used for all stdio inputs and outputs.Default:'buffer'.
  • shell<boolean> |<string> Iftrue, runscommand inside of a shell. Uses'/bin/sh' on Unix, andprocess.env.ComSpec on Windows. A differentshell can be specified as a string. SeeShell requirements andDefault Windows shell.Default:false (no shell).
  • windowsVerbatimArguments<boolean> No quoting or escaping of arguments isdone on Windows. Ignored on Unix. This is set totrue automaticallywhenshell is specified and is CMD.Default:false.
  • windowsHide<boolean> Hide the subprocess console window that wouldnormally be created on Windows systems.Default:false.
• Returns:<Object>
  • pid<number> Pid of the child process.
  • output<Array> Array of results from stdio output.
  • stdout<Buffer> |<string> The contents ofoutput[1].
  • stderr<Buffer> |<string> The contents ofoutput[2].
  • status<number> |<null> The exit code of the subprocess, ornull if thesubprocess terminated due to a signal.
  • signal<string> |<null> The signal used to kill the subprocess, ornull ifthe subprocess did not terminate due to a signal.
  • error<Error> The error object if the child process failed or timed out.

Thechild_process.spawnSync() method is generally identical tochild_process.spawn() with the exception that the function will not returnuntil the child process has fully closed. When a timeout has been encounteredandkillSignal is sent, the method won't return until the process hascompletely exited. If the process intercepts and handles theSIGTERM signaland doesn't exit, the parent process will wait until the child process hasexited.

If theshell option is enabled, do not pass unsanitized user input to thisfunction. Any input containing shell metacharacters may be used to triggerarbitrary command execution.

Event:'close'#

• code<number> The exit code if the child process exited on its own, ornull if the child process terminated due to a signal.
• signal<string> The signal by which the child process was terminated, ornull if the child process did not terminated due to a signal.

The'close' event is emitted after a process has endedand the stdiostreams of a child process have been closed. This is distinct from the'exit' event, since multiple processes might share the same stdiostreams. The'close' event will always emit after'exit' wasalready emitted, or'error' if the child process failed to spawn.

If the process exited,code is the final exit code of the process, otherwisenull. If the process terminated due to receipt of a signal,signal is thestring name of the signal, otherwisenull. One of the two will always benon-null.

const { spawn } =require('node:child_process');const ls =spawn('ls', ['-lh','/usr']);ls.stdout.on('data',(data) => {console.log(`stdout:${data}`);});ls.on('close',(code) => {console.log(`child process close all stdio with code${code}`);});ls.on('exit',(code) => {console.log(`child process exited with code${code}`);});import { spawn }from'node:child_process';const ls =spawn('ls', ['-lh','/usr']);ls.stdout.on('data',(data) => {console.log(`stdout:${data}`);});ls.on('close',(code) => {console.log(`child process close all stdio with code${code}`);});ls.on('exit',(code) => {console.log(`child process exited with code${code}`);});copy

Event:'disconnect'#

The'disconnect' event is emitted after calling thesubprocess.disconnect() method in parent process orprocess.disconnect() in child process. After disconnecting it is no longerpossible to send or receive messages, and thesubprocess.connectedproperty isfalse.

Event:'error'#

• err<Error> The error.

The'error' event is emitted whenever:

• The process could not be spawned.
• The process could not be killed.
• Sending a message to the child process failed.
• The child process was aborted via thesignal option.

The'exit' event may or may not fire after an error has occurred. Whenlistening to both the'exit' and'error' events, guardagainst accidentally invoking handler functions multiple times.

See alsosubprocess.kill() andsubprocess.send().

Event:'exit'#

• code<number> The exit code if the child process exited on its own, ornull if the child process terminated due to a signal.
• signal<string> The signal by which the child process was terminated, ornull if the child process did not terminated due to a signal.

The'exit' event is emitted after the child process ends. If the processexited,code is the final exit code of the process, otherwisenull. If theprocess terminated due to receipt of a signal,signal is the string name ofthe signal, otherwisenull. One of the two will always be non-null.

When the'exit' event is triggered, child process stdio streams might still beopen.

Node.js establishes signal handlers forSIGINT andSIGTERM and Node.jsprocesses will not terminate immediately due to receipt of those signals.Rather, Node.js will perform a sequence of cleanup actions and then willre-raise the handled signal.

Seewaitpid(2).

Event:'message'#

• message<Object> A parsed JSON object or primitive value.
• sendHandle<Handle> |<undefined>undefined or anet.Socket,net.Server, ordgram.Socket object.

The'message' event is triggered when a child process usesprocess.send() to send messages.

The message goes through serialization and parsing. The resultingmessage might not be the same as what is originally sent.

If theserialization option was set to'advanced' used when spawning thechild process, themessage argument can contain data that JSON is not ableto represent.SeeAdvanced serialization for more details.

Event:'spawn'#

The'spawn' event is emitted once the child process has spawned successfully.If the child process does not spawn successfully, the'spawn' event is notemitted and the'error' event is emitted instead.

If emitted, the'spawn' event comes before all other events and before anydata is received viastdout orstderr.

The'spawn' event will fire regardless of whether an error occurswithinthe spawned process. For example, ifbash some-command spawns successfully,the'spawn' event will fire, thoughbash may fail to spawnsome-command.This caveat also applies when using{ shell: true }.

subprocess.channel#

• Type:<Object> A pipe representing the IPC channel to the child process.

Thesubprocess.channel property is a reference to the child's IPC channel. Ifno IPC channel exists, this property isundefined.

subprocess.connected#

• Type:<boolean> Set tofalse aftersubprocess.disconnect() is called.

Thesubprocess.connected property indicates whether it is still possible tosend and receive messages from a child process. Whensubprocess.connected isfalse, it is no longer possible to send or receive messages.

subprocess.disconnect()#

Closes the IPC channel between parent and child processes, allowing the childprocess to exit gracefully once there are no other connections keeping it alive.After calling this method thesubprocess.connected andprocess.connected properties in both the parent and child processes(respectively) will be set tofalse, and it will be no longer possibleto pass messages between the processes.

The'disconnect' event will be emitted when there are no messages in theprocess of being received. This will most often be triggered immediately aftercallingsubprocess.disconnect().

When the child process is a Node.js instance (e.g. spawned usingchild_process.fork()), theprocess.disconnect() method can be invokedwithin the child process to close the IPC channel as well.

subprocess.exitCode#

• Type:<integer>

Thesubprocess.exitCode property indicates the exit code of the child process.If the child process is still running, the field will benull.

subprocess.kill([signal])#

• signal<number> |<string>
• Returns:<boolean>

Thesubprocess.kill() method sends a signal to the child process. If noargument is given, the process will be sent the'SIGTERM' signal. Seesignal(7) for a list of available signals. This function returnstrue ifkill(2) succeeds, andfalse otherwise.

const { spawn } =require('node:child_process');const grep =spawn('grep', ['ssh']);grep.on('close',(code, signal) => {console.log(`child process terminated due to receipt of signal${signal}`);});// Send SIGHUP to process.grep.kill('SIGHUP');import { spawn }from'node:child_process';const grep =spawn('grep', ['ssh']);grep.on('close',(code, signal) => {console.log(`child process terminated due to receipt of signal${signal}`);});// Send SIGHUP to process.grep.kill('SIGHUP');copy

TheChildProcess object may emit an'error' event if the signalcannot be delivered. Sending a signal to a child process that has already exitedis not an error but may have unforeseen consequences. Specifically, if theprocess identifier (PID) has been reassigned to another process, the signal willbe delivered to that process instead which can have unexpected results.

While the function is calledkill, the signal delivered to the child processmay not actually terminate the process.

Seekill(2) for reference.

On Windows, where POSIX signals do not exist, thesignal argument will beignored except for'SIGKILL','SIGTERM','SIGINT' and'SIGQUIT', and theprocess will always be killed forcefully and abruptly (similar to'SIGKILL').SeeSignal Events for more details.

On Linux, child processes of child processes will not be terminatedwhen attempting to kill their parent. This is likely to happen when running anew process in a shell or with the use of theshell option ofChildProcess:

const { spawn } =require('node:child_process');const subprocess =spawn('sh',  ['-c',`node -e "setInterval(() => {      console.log(process.pid, 'is alive')    }, 500);"`,  ], {stdio: ['inherit','inherit','inherit'],  },);setTimeout(() => {  subprocess.kill();// Does not terminate the Node.js process in the shell.},2000);import { spawn }from'node:child_process';const subprocess =spawn('sh',  ['-c',`node -e "setInterval(() => {      console.log(process.pid, 'is alive')    }, 500);"`,  ], {stdio: ['inherit','inherit','inherit'],  },);setTimeout(() => {  subprocess.kill();// Does not terminate the Node.js process in the shell.},2000);copy

subprocess[Symbol.dispose]()#

Callssubprocess.kill() with'SIGTERM'.

subprocess.killed#

• Type:<boolean> Set totrue aftersubprocess.kill() is used to successfullysend a signal to the child process.

Thesubprocess.killed property indicates whether the child processsuccessfully received a signal fromsubprocess.kill(). Thekilled propertydoes not indicate that the child process has been terminated.

subprocess.pid#

• Type:<integer> |<undefined>

Returns the process identifier (PID) of the child process. If the child processfails to spawn due to errors, then the value isundefined anderror isemitted.

const { spawn } =require('node:child_process');const grep =spawn('grep', ['ssh']);console.log(`Spawned child pid:${grep.pid}`);grep.stdin.end();import { spawn }from'node:child_process';const grep =spawn('grep', ['ssh']);console.log(`Spawned child pid:${grep.pid}`);grep.stdin.end();copy

subprocess.ref()#

Callingsubprocess.ref() after making a call tosubprocess.unref() willrestore the removed reference count for the child process, forcing the parentprocess to wait for the child process to exit before exiting itself.

const { spawn } =require('node:child_process');const process =require('node:process');const subprocess =spawn(process.argv[0], ['child_program.js'], {detached:true,stdio:'ignore',});subprocess.unref();subprocess.ref();import { spawn }from'node:child_process';import processfrom'node:process';const subprocess =spawn(process.argv[0], ['child_program.js'], {detached:true,stdio:'ignore',});subprocess.unref();subprocess.ref();copy

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

• message<Object>
• sendHandle<Handle> |<undefined>undefined, or anet.Socket,net.Server, ordgram.Socket object.
• options<Object> Theoptions argument, if present, is an object used toparameterize the sending of certain types of handles.options supportsthe 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>

When an IPC channel has been established between the parent and child processes( i.e. when usingchild_process.fork()), thesubprocess.send() methodcan be used to send messages to the child process. When the child process is aNode.js instance, these messages can be received via the'message' event.

The message goes through serialization and parsing. The resultingmessage might not be the same as what is originally sent.

For example, in the parent script:

const { fork } =require('node:child_process');const forkedProcess =fork(`${__dirname}/sub.js`);forkedProcess.on('message',(message) => {console.log('PARENT got message:', message);});// Causes the child to print: CHILD got message: { hello: 'world' }forkedProcess.send({hello:'world' });import { fork }from'node:child_process';const forkedProcess =fork(`${import.meta.dirname}/sub.js`);forkedProcess.on('message',(message) => {console.log('PARENT got message:', message);});// Causes the child to print: CHILD got message: { hello: 'world' }forkedProcess.send({hello:'world' });copy

And then the child script,'sub.js' might look like this:

process.on('message',(message) => {console.log('CHILD got message:', message);});// Causes the parent to print: PARENT got message: { foo: 'bar', baz: null }process.send({foo:'bar',baz:NaN });copy

Child Node.js processes will have aprocess.send() method of their ownthat allows the child process to send messages back to the parent process.

There is a special case when sending a{cmd: 'NODE_foo'} message. Messagescontaining aNODE_ prefix in thecmd property are reserved for use withinNode.js core and will not be emitted in the child's'message'event. Rather, such messages are emitted using the'internalMessage' event and are consumed internally by Node.js.Applications should avoid using such messages or listening for'internalMessage' events as it is subject to change without notice.

The optionalsendHandle argument that may be passed tosubprocess.send() isfor passing a TCP server or socket object to the child process. The child process willreceive the object as the second argument passed to the callback functionregistered on the'message' event. Any data that is receivedand buffered in the socket will not be sent to the child. Sending IPC sockets isnot supported on Windows.

The optionalcallback is a function that is invoked after the message issent but before the child process may have received it. The function is called with asingle argument:null on success, or anError object on failure.

If nocallback function is provided and the message cannot be sent, an'error' event will be emitted by theChildProcess object. This canhappen, for instance, when the child process has already exited.

subprocess.send() will returnfalse if the channel has closed or when thebacklog of unsent messages exceeds a threshold that makes it unwise to sendmore. Otherwise, the method returnstrue. Thecallback function can beused to implement flow control.

const { fork } =require('node:child_process');const { createServer } =require('node:net');const subprocess =fork('subprocess.js');// Open up the server object and send the handle.const server =createServer();server.on('connection',(socket) => {  socket.end('handled by parent');});server.listen(1337,() => {  subprocess.send('server', server);});import { fork }from'node:child_process';import { createServer }from'node:net';const subprocess =fork('subprocess.js');// Open up the server object and send the handle.const server =createServer();server.on('connection',(socket) => {  socket.end('handled by parent');});server.listen(1337,() => {  subprocess.send('server', server);});copy

process.on('message',(m, server) => {if (m ==='server') {    server.on('connection',(socket) => {      socket.end('handled by child');    });  }});copy

const { fork } =require('node:child_process');const { createServer } =require('node:net');const normal =fork('subprocess.js', ['normal']);const special =fork('subprocess.js', ['special']);// Open up the server and send sockets to child. Use pauseOnConnect to prevent// the sockets from being read before they are sent to the child process.const server =createServer({pauseOnConnect:true });server.on('connection',(socket) => {// If this is special priority...if (socket.remoteAddress ==='74.125.127.100') {    special.send('socket', socket);return;  }// This is normal priority.  normal.send('socket', socket);});server.listen(1337);import { fork }from'node:child_process';import { createServer }from'node:net';const normal =fork('subprocess.js', ['normal']);const special =fork('subprocess.js', ['special']);// Open up the server and send sockets to child. Use pauseOnConnect to prevent// the sockets from being read before they are sent to the child process.const server =createServer({pauseOnConnect:true });server.on('connection',(socket) => {// If this is special priority...if (socket.remoteAddress ==='74.125.127.100') {    special.send('socket', socket);return;  }// This is normal priority.  normal.send('socket', socket);});server.listen(1337);copy

process.on('message',(m, socket) => {if (m ==='socket') {if (socket) {// Check that the client socket exists.// It is possible for the socket to be closed between the time it is// sent and the time it is received in the child process.      socket.end(`Request handled with${process.argv[2]} priority`);    }  }});copy

subprocess.signalCode#

• Type:<string> |<null>

Thesubprocess.signalCode property indicates the signal received bythe child process if any, elsenull.

subprocess.spawnargs#

• Type:<Array>

Thesubprocess.spawnargs property represents the full list of command-linearguments the child process was launched with.

subprocess.spawnfile#

• Type:<string>

Thesubprocess.spawnfile property indicates the executable file name ofthe child process that is launched.

Forchild_process.fork(), its value will be equal toprocess.execPath.Forchild_process.spawn(), its value will be the name ofthe executable file.Forchild_process.exec(), its value will be the name of the shellin which the child process is launched.

subprocess.stderr#

• Type:<stream.Readable> |<null> |<undefined>

AReadable Stream that represents the child process'sstderr.

If the child process was spawned withstdio[2] set to anything other than'pipe',then this will benull.

subprocess.stderr is an alias forsubprocess.stdio[2]. Both properties willrefer to the same value.

Thesubprocess.stderr property can benull orundefinedif the child process could not be successfully spawned.

subprocess.stdin#

• Type:<stream.Writable> |<null> |<undefined>

AWritable Stream that represents the child process'sstdin.

If a child process waits to read all of its input, the child process will not continueuntil this stream has been closed viaend().

If the child process was spawned withstdio[0] set to anything other than'pipe',then this will benull.

subprocess.stdin is an alias forsubprocess.stdio[0]. Both properties willrefer to the same value.

Thesubprocess.stdin property can benull orundefinedif the child process could not be successfully spawned.

subprocess.stdio#

• Type:<Array>

A sparse array of pipes to the child process, corresponding with positions inthestdio option passed tochild_process.spawn() that have been setto the value'pipe'.subprocess.stdio[0],subprocess.stdio[1], andsubprocess.stdio[2] are also available assubprocess.stdin,subprocess.stdout, andsubprocess.stderr, respectively.

In the following example, only the child's fd1 (stdout) is configured as apipe, so only the parent'ssubprocess.stdio[1] is a stream, all other valuesin the array arenull.

const assert =require('node:assert');const fs =require('node:fs');const child_process =require('node:child_process');const subprocess = child_process.spawn('ls', {stdio: [0,// Use parent's stdin for child.'pipe',// Pipe child's stdout to parent.    fs.openSync('err.out','w'),// Direct child's stderr to a file.  ],});assert.strictEqual(subprocess.stdio[0],null);assert.strictEqual(subprocess.stdio[0], subprocess.stdin);assert(subprocess.stdout);assert.strictEqual(subprocess.stdio[1], subprocess.stdout);assert.strictEqual(subprocess.stdio[2],null);assert.strictEqual(subprocess.stdio[2], subprocess.stderr);import assertfrom'node:assert';import fsfrom'node:fs';import child_processfrom'node:child_process';const subprocess = child_process.spawn('ls', {stdio: [0,// Use parent's stdin for child.'pipe',// Pipe child's stdout to parent.    fs.openSync('err.out','w'),// Direct child's stderr to a file.  ],});assert.strictEqual(subprocess.stdio[0],null);assert.strictEqual(subprocess.stdio[0], subprocess.stdin);assert(subprocess.stdout);assert.strictEqual(subprocess.stdio[1], subprocess.stdout);assert.strictEqual(subprocess.stdio[2],null);assert.strictEqual(subprocess.stdio[2], subprocess.stderr);copy

Thesubprocess.stdio property can beundefined if the child process couldnot be successfully spawned.

subprocess.stdout#

• Type:<stream.Readable> |<null> |<undefined>

AReadable Stream that represents the child process'sstdout.

If the child process was spawned withstdio[1] set to anything other than'pipe',then this will benull.

subprocess.stdout is an alias forsubprocess.stdio[1]. Both properties willrefer to the same value.

const { spawn } =require('node:child_process');const subprocess =spawn('ls');subprocess.stdout.on('data',(data) => {console.log(`Received chunk${data}`);});import { spawn }from'node:child_process';const subprocess =spawn('ls');subprocess.stdout.on('data',(data) => {console.log(`Received chunk${data}`);});copy

Thesubprocess.stdout property can benull orundefinedif the child process could not be successfully spawned.

subprocess.unref()#

By default, the parent process will wait for the detached child process to exit.To prevent the parent process from waiting for a givensubprocess to exit, use thesubprocess.unref() method. Doing so will cause the parent's event loop to notinclude the child process in its reference count, allowing the parent to exitindependently of the child, unless there is an established IPC channel betweenthe child and the parent processes.

const { spawn } =require('node:child_process');const process =require('node:process');const subprocess =spawn(process.argv[0], ['child_program.js'], {detached:true,stdio:'ignore',});subprocess.unref();import { spawn }from'node:child_process';import processfrom'node:process';const subprocess =spawn(process.argv[0], ['child_program.js'], {detached:true,stdio:'ignore',});subprocess.unref();copy