Stability: 2 - Stable
The module provides the ability to spawn child processes in a manner that is similar, but not identical, to popen(3).
This capability is primarily provided by the function:
By default, pipes for and are established between the parent Node.js process and the spawned child.
These pipes have limited (and platform-specific) capacity.
If the child process writes to in excess of that limit without the output being captured, the child process will block waiting for the pipe buffer to accept more data.
This is identical to the behavior of pipes in the shell.
Use the option if the output will not be consumed.
The method spawns the child process asynchronously, without blocking the Node.js event loop.
The function provides equivalent functionality in a synchronous manner that blocks the event loop until the spawned process either exits or is terminated.
For convenience, the module provides a handful of synchronous and asynchronous alternatives to and
Note that each of these alternatives are implemented on top of or
spawns a shell and runs a command within that shell, passing the and to a callback function when complete.
similar to 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.
a synchronous version of that block the Node.js event loop.
For certain use cases, such as automating shell scripts, the synchronous counterparts may be more convenient.
In many cases, however, the synchronous methods can have significant impact on performance due to stalling the event loop while spawned processes complete.
Asynchronous Process Creation
The and methods all follow the idiomatic asynchronous programming pattern typical of other Node.js APIs.
Each of the methods returns a instance. These objects implement the Node.js API, allowing the parent process to register listener functions that are called when certain events occur during the life cycle of the child process.
The and methods additionally allow for an optional callback function to be specified that is invoked when the child process terminates.
Spawning and files on Windows
The importance of the distinction between and can vary based on platform.
On Unix-type operating systems (Unix, Linux, macOS) can be more efficient because it does not spawn a shell by default.
On Windows, however, and files are not executable on their own without a terminal, and therefore cannot be launched using
When running on Windows, and files can be invoked using with the option set, with, or by spawning and passing the or file as an argument (which is what the option and do).
In any case, if the script filename contains spaces it needs to be quoted.
On Windows Only ...
Script with spaces in the filename:
The command to run, with space-separated arguments.
Current working directory of the child process.
Environment key-value pairs.
Shell to execute the command with.
See Shell Requirements and Default Windows Shell
Largest amount of data in bytes allowed on or
If exceeded, the child process is terminated.
See caveat at
Sets the user identity of the process
Sets the group identity of the process
Hide the subprocess console window that would normally be created on Windows systems.
called with the output when process terminates.
Spawns a shell then executes the within that shell, buffering any generated output.
The string passed to the exec function is processed directly by the shell and special characters (vary based on) need to be dealt with accordingly:
Double quotes are used so that the space in the path is not interpreted as multiple arguments
Never pass unsanitized user input to this function.
Any input containing shell metacharacters may be used to trigger arbitrary command execution.
If a function is provided, it is called with the arguments
On success, will be
On error, will be an instance of
The property will be the exit code of the child process while will be set to the signal that terminated the process.
Any exit code other than is considered to be an error.
The and arguments passed to the callback will contain the and output of the child process.
By default, Node.js will decode the output as UTF-8 and pass strings to the callback.
The option can be used to specify the character encoding used to decode the and output.
If is, or an unrecognized character encoding, objects will be passed to the callback instead.
If is greater than, the parent will send the signal identified by the property (the default is) if the child runs longer than milliseconds.
Unlike the exec(3) POSIX system call, does not replace the existing process and uses a shell to execute the command.
If this method is invoked as its ed version, it returns a for an with and properties.
In case of an error (including any error resulting in an exit code other than 0), a rejected promise is returned, with the same object given in the callback, but with an additional two properties and
The name or path of the executable file to run.
List of string arguments.
No quoting or escaping of arguments is done on Windows.
Ignored on Unix.
If, runs inside of a shell.
Called with the output when process terminates.
The function is similar to except that it does not spawn a shell by default.
Rather, the specified executable is spawned directly as a new process making it slightly more efficient than
The same options as are supported.
Since a shell is not spawned, behaviors such as I/O redirection and file globbing are not supported.
If the option is enabled, do not pass unsanitized user input to this function.
The method is a special case of used specifically to spawn new Node.js processes.
Like a object is returned.
The returned will have an additional communication channel built-in that allows messages to be passed back and forth between the parent and child.
See for details.
It is important to keep in mind that spawned Node.js child processes are independent of the parent with exception of the IPC communication channel that is established between the two. Each process has its own memory, with their own V8 instances. Because of the additional resource allocations required, spawning a large number of child Node.js processes is not recommended.
By default, will spawn new Node.js instances using the of the parent process.
The property in the object allows for an alternative execution path to be used.
Node.js processes launched with a custom will communicate with the parent process using the file descriptor (fd) identified using the environment variable on the child process.
Unlike the fork(2) POSIX system call, does not clone the current process.
The option available in is not supported by and will be ignored if set.