Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท child_process, worker_threads and cluster

Node.js child_process stdio options

How the stdio option of spawn, fork and execFile works in Node.js: pipe, inherit, ignore, file descriptors, shared streams, extra pipes and the ipc channel.

Every process starts with three standard streams: file descriptor 0 (input), 1 (output) and 2 (errors). The stdio option of spawn(), fork(), spawnSync() and friends decides what each of the child's descriptors is connected to. The default is to give your program a pipe for each of them, which appear as child.stdin, child.stdout and child.stderr.

Changing stdio is how you print a child's output straight to your terminal, discard it, write it to a file, or open extra channels beyond the three standard ones. You can give one value for all three (stdio: 'inherit') or an array with one entry per descriptor.

NODE
import { spawn } from 'node:child_process';

spawn('ls', { stdio: 'inherit' });                       // share the parent's streams
spawn('ls', { stdio: ['ignore', 'pipe', 'inherit'] });   // per-descriptor control

Try it

Node.js pipe, ignore and a file descriptor

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 inherit, stdin and an extra pipe

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.

The values you can use

stdio is either a string (the same setting for descriptors 0, 1 and 2) or an array whose index is the descriptor number. Each entry can be:

Entry Meaning
'pipe' Create a pipe. The parent end appears as child.stdin, child.stdout, child.stderr or child.stdio[n].
'overlapped' Like 'pipe', but opened for overlapped I/O on Windows. Same as 'pipe' elsewhere.
'ignore' Connect the descriptor to /dev/null (NUL on Windows). Writes are discarded, reads see end of input.
'inherit' Share the parent's descriptor. Equivalent to [process.stdin, process.stdout, process.stderr][i] or the number i. The matching child.stdio[i] is null.
'ipc' Create the message channel used by fork() and IPC messaging. At most one per child.
a Stream object Any stream with an underlying file descriptor (a file stream that is open, a socket, a TTY). The child uses that descriptor.
a positive integer An already open file descriptor in the parent, shared with the child.
null or undefined Default: 'pipe' for descriptors 0, 1, 2, and 'ignore' for index 3 and above.

Usage notes

  • Shorthand strings: 'pipe', 'ignore' and 'inherit' as a single value apply to all three standard streams. 'ipc' is not allowed as a single string.
  • Entries beyond index 2 create extra descriptors for the child (fd 3, 4, ...). The child must know to use them; programs such as Node read them by number, for example with fs.writeSync(3, ...).
  • Unread pipes can deadlock. A pipe has a limited buffer. A chatty child blocks when nobody reads its stdout. Read the stream, set 'ignore', or redirect to a file.
  • 'inherit' and captured output exclude each other. With 'inherit' there is nothing to read in the parent (child.stdout is null); execFile() and exec() rely on pipes, so they cannot capture inherited streams.
  • Descriptor numbers must be open. Passing a closed descriptor number to a child fails or behaves unpredictably. Open the file with fs.openSync() first and close it in the parent when the child has started or finished.
  • Interactive programs (editors, password prompts, tools that check for a terminal) need stdio: 'inherit', because a pipe is not a TTY.
  • Closing stdin with child.stdin.end() is how you tell programs such as sort or wc that input is complete. Forgetting it makes them wait forever.
  • Detached children that must outlive the parent should not hold pipes to it; use 'ignore' or file descriptors. See Detached processes.