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:
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}`);
});
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 as PATH 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
stdoutandstderrto 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.
Instances of the ChildProcess represent spawned child processes.
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.
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 SIGTERM signal and doesn't exit, the parent process will wait until the child process
has exited.
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.
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.
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.