Node.js Reference ยท child_process, worker_threads and cluster
The Node.js ChildProcess class
Reference for the ChildProcess class in Node.js: the object returned by spawn, exec and fork, with its events, stdio streams, kill(), exit codes and properties.
A ChildProcess is the handle your program gets for a process it started. It is returned by spawn(), exec(), execFile() and fork(). You do not create one with new. It is an EventEmitter that reports the child's life cycle and gives you its standard streams, its process id and a way to stop it.
The class does not run anything itself; the operating system does. The object tells you what happened: whether the process started, what it printed, how it ended. Reading it correctly is mostly about knowing the order of events and which of them can be missing.
import { spawn } from 'node:child_process'; const child = spawn(process.execPath, ['-e', 'console.log("hi")']); child.stdout.on('data', (chunk) => console.log(String(chunk))); child.on('close', (code, signal) => console.log(code, signal));
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
class ChildProcess extends EventEmitter { pid: number | undefined; stdin: Writable | null; stdout: Readable | null; stderr: Readable | null; stdio: [Writable | null, Readable | null, Readable | null, ...]; exitCode: number | null; signalCode: string | null; killed: boolean; connected: boolean; spawnfile: string; spawnargs: string[]; kill(signal?: string | number): boolean; send(message, sendHandle?, options?, callback?): boolean; disconnect(): void; ref(): void; unref(): void; }
Events
| Event | Description |
|---|---|
'spawn' |
The process was started. Not emitted if starting failed. |
'error' |
The process could not be spawned, could not be killed, a message could not be sent, or an abort signal fired. Not emitted for a non-zero exit. |
'exit' |
The process ended. Arguments (code, signal): exactly one is null. The stdio streams may still hold data. |
'close' |
The process ended and all stdio streams are closed. Same (code, signal) arguments. Use this one to know that all output has been read. |
'disconnect' |
The IPC channel closed (after disconnect(), or because either side exited). |
'message' |
A message arrived over the IPC channel (see IPC messaging). |
Properties and methods
| Name | Description |
|---|---|
pid |
The process id, or undefined if the spawn failed. |
stdin, stdout, stderr |
Streams, or null if the matching stdio entry is not 'pipe'. |
stdio |
Array of every stdio entry, including extra descriptors. |
exitCode |
The exit code after the process ended, null before or when ended by a signal. |
signalCode |
The signal name that ended the process, or null. |
killed |
true once kill() has successfully sent a signal. It does not mean the process has died. |
connected |
true while the IPC channel is open. |
spawnfile, spawnargs |
The executable and the full argument list including argv[0]. |
kill([signal]) |
Sends a signal (default 'SIGTERM'). Returns true if the signal was delivered to the process. |
ref(), unref() |
Make the parent wait (default) or not wait for this child before it exits. |
Usage notes
- Always listen for
'error'. An unhandled'error'event on anEventEmitterthrows. Spawning a missing program is the usual trigger. See the error event. - Prefer
'close'over'exit'when you collect output: at'exit'time buffered data may still be arriving onstdout. - Code or signal, never both. A child killed by
SIGTERMreports(null, 'SIGTERM'). Treatcode === 0as success and checksignalseparately. kill()is a request. The child can catchSIGTERMand keep running;SIGKILLcannot be caught.child.killedbecomingtrueonly means a signal was sent.- Unread streams can stall a child. If the child writes more than the pipe buffer holds and nobody reads
stdout, the child blocks. Consume the streams or usestdio: 'ignore'. ref()andunref(). A running child keeps the parent alive.unref()lets the parent exit first; it is mostly useful with detached processes.- Disposal.
ChildProcessimplementsSymbol.dispose, which callskill(), sousing child = spawn(...)ends the child at the end of the block. - Not on Windows. Signals other than
SIGKILL,SIGTERMandSIGINThave no real effect on Windows;kill()there always ends the process forcibly.