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.
Classes #
Instances of the ChildProcess represent spawned child processes.
Functions #
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.