Node.js Child Process Module

The node:child_process module provides the ability to spawn subprocesses in a manner that is similar, but not identical, to popen(3).

This capability is primarily provided by the child_process.spawn() function.

The child_process.spawn(), child_process.fork(), child_process.exec(), and child_process.execFile() methods all follow the idiomatic asynchronous programming pattern typical of other Node.js APIs.

The importance of the distinction between child_process.exec() and child_process.execFile() can vary based on platform.

Spawns a shell and runs a command within that shell, passing the stdout and stderr to a callback function when complete.

If a callback function is provided, it is called with the arguments (error, stdout, stderr).

On success, error will be null.

On error, error will be an instance of Error.

If the signal option is enabled, calling .abort() on the corresponding AbortController is similar to calling .kill() on the child process except the error passed to the callback will be an AbortError.

Similar to child_process.exec() except that it spawns the command directly without first spawning a shell by default.

Spawns a new Node.js process and invokes a specified module with an IPC communication channel established that allows sending messages between parent and child.

The method spawns a new process using the given command, with command-line arguments in args.

If omitted, args defaults to an empty array.

Example of running ls -lh /usr.

A very elaborate way to run ps ax | grep ssh

Example of checking for failed spawn.

On Windows, setting options.detached to true makes it possible for the child process to continue running after the parent exits. The child process will have its own console window. Once enabled for a child process, it cannot be disabled.

The options.stdio option is used to configure the pipes that are established between the parent and child process.

The child_process.spawnSync(), child_process.execSync(), and child_process.execFileSync() methods are synchronous and will block the Node.js event loop, pausing execution of any additional code until the spawned process exits.

A synchronous version of child_process.execFile() that will block the Node.js event loop.

A synchronous version of child_process.exec() that will block the Node.js event loop.

The method is generally identical to child_process.spawn() with the exception that the function will not return until the child process has fully closed.

Extends: <EventEmitter>

Instances of the ChildProcess represent spawned child processes.

The event is emitted after a process has ended and the stdio streams of a child process have been closed.

The event is emitted after calling the subprocess.disconnect() method in parent process or process.disconnect() in child process.

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

The event is emitted after the child process ends.

The event is triggered when a child process uses process.send() to send messages.

The event is emitted once the child process has spawned successfully.

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

The subprocess.channel property is a reference to the child's IPC channel.

If no IPC channel exists, this property is undefined.

This method makes the IPC channel keep the event loop of the parent process running if .unref() has been called before.

This method makes the IPC channel not keep the event loop of the parent process running, and lets it finish even while the channel is open.

<boolean> Set to false after subprocess.disconnect() is called.

The subprocess.connected property indicates whether it is still possible to send and receive messages from a child process.

Closes the IPC channel between parent and child processes, allowing the child process to exit gracefully once there are no other connections keeping it alive.

The property indicates the exit code of the child process.

If the child process is still running, the field will be null.

The method sends a signal to the child process.

<boolean> Set to true after subprocess.kill() is used to successfully send a signal to the child process.

The property indicates whether the child process successfully received a signal from subprocess.kill().

<integer> | <undefined>

Returns the process identifier (PID) of the child process.

If the child process fails to spawn due to errors, then the value is undefined and error is emitted.

Calling subprocess.ref() after making a call to subprocess.unref() will restore the removed reference count for the child process, forcing the parent process to wait for the child process to exit before exiting itself.

The subprocess.send() method can be used to send messages to the child process.

The sendHandle argument can be used, for instance, to pass the handle of a TCP server object to the child process as illustrated in the example below.

Similarly, the sendHandler argument can be used to pass the handle of a socket to the child process. The example below spawns two children that each handle connections with "normal" or "special" priority.

<string> | <null>

The subprocess.signalCode property indicates the signal received by the child process if any, else null.

<Array>

The subprocess.spawnargs property represents the full list of command-line arguments the child process was launched with.

<string>

The subprocess.spawnfile property indicates the executable file name of the child process that is launched.

<stream.Readable> | <null> | <undefined>

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

<stream.Writable> | <null> | <undefined>

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

<Array>

A sparse array of pipes to the child process, corresponding with positions in the stdio option passed to child_process.spawn().

<stream.Readable> | <null> | <undefined>

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

By default, the parent process will wait for the detached child process to exit. To prevent the parent process from waiting for a given subprocess to exit, use the subprocess.unref() method.

Child processes support a serialization mechanism for IPC that is based on the serialization API of the node:v8 module, based on the HTML structured clone algorithm.