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.
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
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.
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.stdoutisnull);execFile()andexec()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 assortorwcthat 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.