Child Process

The child_process module provides the ability to spawn child processes

By default, pipes for stdin, stdout and stderr are established between
the parent process and the spawned child.

The [child_process.spawn()][] method spawns the child process asynchronously,
without blocking the event loop.

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

Ruff available: v1.6.0

  • command {String} The command to run
  • args {Array} List of string arguments
  • options {Object}
    • cwd {String} Current working directory of the child process
    • env {Object} Environment key-value pairs
    • argv0 {String} Explicitly set the value of argv[0] sent to the child
      process. This will be set to command if not specified.
    • stdio {Array|String} Child’s stdio configuration. (See
    • detached {Boolean} Prepare child to run independently of its parent
      process. Specific behavior depends on the platform, see
    • uid {Number} Sets the user identity of the process. (See setuid(2).)
    • gid {Number} Sets the group identity of the process. (See setgid(2).)
  • return: {ChildProcess}

The child_process.spawn() method spawns a new process using the given
command, with command line arguments in args. If omitted, args defaults
to an empty array.

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

cwd: undefined,
env: process.env

Use cwd to specify the working directory from which the process is spawned.
If not given, the default is to inherit the current working directory.

Use env to specify environment variables that will be visible to the new
process, the default is [process.env][].

Example of running ls -lh /, capturing stdout, stderr, and the
exit code:

const spawn = require('child_process').spawn;
const ls = spawn('ls', ['-lh', '/']);

ls.stdout.on('data', function (data) {
console.log('stdout:', data);

ls.stderr.on('data', function (data) {
console.log('stderr:', data);

ls.on('exit', function (code) {
console.log('child process exited with code:', code);


The options.stdio option is used to configure the pipes that are established
between the parent and child process. By default, the child’s stdin, stdout,
and stderr are redirected to corresponding [child.stdin][], [child.stdout][], and
[child.stderr][] streams on the [ChildProcess][] object. This is equivalent to
setting the options.stdio equal to ['pipe', 'pipe', 'pipe'].

For convenience, options.stdio may be one of the following strings:

  • 'pipe' - equivalent to ['pipe', 'pipe', 'pipe'] (the default)
  • 'ignore' - equivalent to ['ignore', 'ignore', 'ignore']
  • 'inherit' - equivalent to [process.stdin, process.stdout, process.stderr]
    or [0,1,2]

Otherwise, the value of options.stdio is an array where each index corresponds
to an fd in the child. The fds 0, 1, and 2 correspond to stdin, stdout,
and stderr, respectively. Additional fds can be specified to create additional
pipes between the parent and child. The value is one of the following:

  1. 'pipe' - Create a pipe between the child process and the parent process.
    The parent end of the pipe is exposed to the parent as a property on the
    child_process object as [child.stdio[fd]][stdio]. Pipes created for
    fds 0 - 2 are also available as [child.stdin][], [child.stdout][]
    and [child.stderr][], respectively.
  2. 'ignore' - Instructs Node.js to ignore the fd in the child. While Node.js
    will always open fds 0 - 2 for the processes it spawns, setting the fd to
    'ignore' will cause Node.js to open /dev/null and attach it to the
    child’s fd.
    corresponds to the index in the stdio array. Note that the stream must
    have an underlying descriptor (file streams do not until the 'open'
    event has occurred).
  3. Positive integer - The integer value is interpreted as a file descriptor
    that is is currently open in the parent process. It is shared with the child
    process, similar to how {Stream} objects can be shared.
  4. null, undefined - Use default value. For stdio fds 0, 1 and 2 (in other
    words, stdin, stdout, and stderr) a pipe is created. For fd 3 and up, the
    default is 'ignore'.

Class: ChildProcess

Instances of the ChildProcess class are [EventEmitters][EventEmitter] that represent
spawned child processes.

Instances of ChildProcess are not intended to be created directly. Rather,
use the [child_process.spawn()][], [child_process.exec()][],
[child_process.execFile()][], or [child_process.fork()][] methods to create
instances of ChildProcess.

Event: ‘error’

  • err {Error} the error.

The 'error' event is emitted whenever:

  1. The process could not be spawned, or
  2. The process could not be killed, or
  3. Sending a message to the child process failed.

Note that the 'exit' event may or may not fire after an error has occurred.
If you are listening to both the 'exit' and 'error' events, it is important
to guard against accidentally invoking handler functions multiple times.

Event: ‘exit’

  • code {Number} the exit code if the child exited on its own.
  • signal {String} the signal by which the child process was terminated.

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


Ruff available: v1.6.0

  • signal {String}


Ruff available: v1.6.0

  • {Stream}

A Readable Stream that represents the child process’s stderr.


Ruff available: v1.6.0

  • {Stream}

A Writable Stream that represents the child process’s stdin.


Ruff available: v1.6.0

  • {Stream}

A Readable Stream that represents the child process’s stdout.