Skip to content
Tutorials Center
My learning

Topics

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.

NODE
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

Node.js The life cycle in order

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.

Node.js kill(), error events and the killed flag

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

NODE
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 an EventEmitter throws. 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 on stdout.
  • Code or signal, never both. A child killed by SIGTERM reports (null, 'SIGTERM'). Treat code === 0 as success and check signal separately.
  • kill() is a request. The child can catch SIGTERM and keep running; SIGKILL cannot be caught. child.killed becoming true only 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 use stdio: 'ignore'.
  • ref() and unref(). A running child keeps the parent alive. unref() lets the parent exit first; it is mostly useful with detached processes.
  • Disposal. ChildProcess implements Symbol.dispose, which calls kill(), so using child = spawn(...) ends the child at the end of the block.
  • Not on Windows. Signals other than SIGKILL, SIGTERM and SIGINT have no real effect on Windows; kill() there always ends the process forcibly.