Invoke external tools
Run a compiler, formatter, or operating-system utility while streaming its output.
Node.js · Module
node:child_process
The node:child_process module launches external commands and Node.js subprocesses. It offers asynchronous and synchronous APIs, stream-based process control, shell command execution, and IPC for forked Node.js processes.
How it works
The module starts external commands or additional Node.js processes. Asynchronous functions return ChildProcess event emitters, while synchronous variants wait for completion and block the event loop; spawned processes can communicate through standard streams, and forked Node.js processes can use IPC.
Syntax
import { spawn, spawnSync, exec, execFile, fork } from 'node:child_process';
spawn(command[, args][, options])Parameters
| Name | Type | Description |
|---|---|---|
command | string | The executable command to start. |
args | string[] | Command-line arguments passed to the executable. |
options | Object | Optional spawn configuration, including standard I/O and environment settings. |
Returns
Asynchronous process-creation methods return a ChildProcess instance; synchronous variants return the completed operation's result or throw on failure.
Key points
- Use this module to create and manage subprocesses from a Node.js application.
- spawn is the default choice for non-blocking process execution and supports handling output as it arrives.
- The main asynchronous creation methods return a ChildProcess object that represents the running subprocess.
- Listen for lifecycle events on the returned ChildProcess instead of polling its status.
- fork is specialized for starting Node.js code rather than arbitrary system commands.
- Pass the executable and its arguments separately to spawn for explicit process construction.
Common mistakes
- Synchronous APIs pause the event loop until the child exits or is terminated; avoid them in latency-sensitive server handlers.
- exec runs through a shell, so interpolating untrusted input can create command-injection risk; prefer argument-based spawning when possible.
- exec and execFile can use callbacks, but their output-collection behavior differs from directly consuming spawn streams.
Example: Spawn a child process
import { spawn } from 'node:child_process';
const child = spawn(process.execPath, ['-e', 'console.log("hello")']);
child.stdout.on('data', (chunk) => {
process.stdout.write(chunk);
});
child.on('close', (code, signal) => {
console.log(`closed: code=${code}, signal=${signal ?? 'none'}`);
});Starts a separate Node.js process asynchronously, reads its standard output, and reports how it ended.
When to use it
Background subprocesses
Launch independent work without blocking the Node.js event loop.
Node.js worker processes with IPC
Start another Node.js module and exchange messages with it.
Callback-based command execution
Run a shell command and receive collected output on completion.
Interview questions
QHow does spawn differ from spawnSync?
spawn starts a command asynchronously and returns a ChildProcess event emitter. Its arguments are supplied separately as a command and an argument array, and its standard streams can be consumed incrementally.
Follow-up: When would exec be preferable? Use it for a shell command when buffered stdout and stderr plus a completion callback are convenient, while recognizing the shell and input-safety implications.
QCompare exec and execFile.
exec starts a shell and runs a command inside it, then can invoke a callback when the process finishes. execFile invokes the executable directly rather than first starting a shell.
Follow-up: Why choose execFile for user-derived values? Keep values in separate argument positions and avoid shell parsing, reducing shell-injection exposure.
QWhat is special about fork?
fork is a specialized form of spawn for launching another Node.js process. It establishes an IPC channel so the parent and child can exchange messages.
Follow-up: What trade-off does fork have? It is intended for Node.js modules and IPC, whereas spawn is the general mechanism for arbitrary executables.
Related
ChildProcessspawnSync()exec()execFile()execSync()execFileSync()fork()