Index - Node documentation

Usage in Deno

import * as mod from "node:child_process";

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 spawn function:

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}`);
});

By default, pipes for stdin, stdout, and stderr are established between the parent Node.js process and the spawned subprocess. These pipes have limited (and platform-specific) capacity. If the subprocess writes to stdout in excess of that limit without the output being captured, the subprocess blocks waiting for the pipe buffer to accept more data. This is identical to the behavior of pipes in the shell. Use the { stdio: 'ignore' }option if the output will not be consumed.

The command lookup is performed using the options.env.PATH environment variable if env is in the options object. Otherwise, process.env.PATH is used. If options.env is set without PATH, lookup on Unix is performed on a default search path search of /usr/bin:/bin (see your operating system's manual for execvpe/execvp), on Windows the current processes environment variable PATH is used.

On Windows, environment variables are case-insensitive. Node.js lexicographically sorts the env keys and uses the first one that case-insensitively matches. Only first (in lexicographic order) entry will be passed to the subprocess. This might lead to issues on Windows when passing objects to the env option that have multiple variants of the same key, such asPATH and Path.

The spawn method spawns the child process asynchronously, without blocking the Node.js event loop. The spawnSync 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 node:child_process module provides a handful of synchronous and asynchronous alternatives to spawn and spawnSync. Each of these alternatives are implemented on top of spawn or spawnSync.

  • exec: spawns a shell and runs a command within that shell, passing the stdout and stderr to a callback function when complete.
  • execFile: similar to exec except that it spawns the command directly without first spawning a shell by default.
  • fork: 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.
  • execSync: a synchronous version of exec that will block the Node.js event loop.
  • execFileSync: a synchronous version of execFile that will 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.

Classes

c
ChildProcess

Instances of the ChildProcess represent spawned child processes.

Functions

f
exec

Spawns a shell then executes the command within that shell, buffering any generated output. The command string passed to the exec function is processed directly by the shell and special characters (vary based on shell) need to be dealt with accordingly:

f
execFile

The child_process.execFile() function is similar to exec except that it does not spawn a shell by default. Rather, the specified executable file is spawned directly as a new process making it slightly more efficient than exec.

f
execFileSync

The child_process.execFileSync() method is generally identical to execFile with the exception that the method will not return until the child process has fully closed. When a timeout has been encountered and killSignal is sent, the method won't return until the process has completely exited.

f
execSync

The child_process.execSync() method is generally identical to exec with the exception that the method will not return until the child process has fully closed. When a timeout has been encountered and killSignal is sent, the method won't return until the process has completely exited. If the child process intercepts and handles the SIGTERMsignal and doesn't exit, the parent process will wait until the child process has exited.

f
fork

The child_process.fork() method is a special case of spawn used specifically to spawn new Node.js processes. Like spawn, a ChildProcess object is returned. The returned ChildProcess will have an additional communication channel built-in that allows messages to be passed back and forth between the parent and child. See subprocess.send() for details.

f
spawn

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

f
spawnSync

The child_process.spawnSync() method is generally identical to spawn with the exception that the function will not return until the child process has fully closed. When a timeout has been encountered and killSignal is sent, the method won't return until the process has completely exited. If the process intercepts and handles the SIGTERM signal and doesn't exit, the parent process will wait until the child process has exited.

Interfaces

I
ChildProcessByStdio
No documentation available
I
ChildProcessWithoutNullStreams
No documentation available
I
CommonExecOptions
No documentation available
I
CommonOptions
No documentation available
I
CommonSpawnOptions
No documentation available
I
ExecException
No documentation available
I
ExecFileOptions
No documentation available
I
ExecFileOptionsWithBufferEncoding
No documentation available
I
ExecFileOptionsWithOtherEncoding
No documentation available
I
ExecFileOptionsWithStringEncoding
No documentation available
I
ExecFileSyncOptions
No documentation available
I
ExecFileSyncOptionsWithBufferEncoding
No documentation available
I
ExecFileSyncOptionsWithStringEncoding
No documentation available
I
ExecOptions
No documentation available
I
ExecOptionsWithBufferEncoding
No documentation available
I
ExecOptionsWithStringEncoding
No documentation available
I
ExecSyncOptions
No documentation available
I
ExecSyncOptionsWithBufferEncoding
No documentation available
I
ExecSyncOptionsWithStringEncoding
No documentation available
I
ForkOptions
No documentation available
I
MessageOptions
No documentation available
I
MessagingOptions
No documentation available
I
ProcessEnvOptions
No documentation available
I
PromiseWithChild
No documentation available
I
SpawnOptions
No documentation available
I
SpawnOptionsWithoutStdio
No documentation available
I
SpawnOptionsWithStdioTuple
No documentation available
I
SpawnSyncOptions
No documentation available
I
SpawnSyncOptionsWithBufferEncoding
No documentation available
I
SpawnSyncOptionsWithStringEncoding
No documentation available
I
SpawnSyncReturns
No documentation available

Type Aliases

T
ExecFileException
No documentation available
T
IOType
No documentation available
T
SendHandle
No documentation available
T
Serializable
No documentation available
T
SerializationType
No documentation available
T
StdioNull
No documentation available
T
StdioOptions
No documentation available
T
StdioPipe
No documentation available
T
StdioPipeNamed
No documentation available