Node.js Reference ยท child_process, worker_threads and cluster
Node.js child_process.spawnSync() method
Reference for child_process.spawnSync() in Node.js: run a program, block until it ends, and read status, signal, stdout and stderr from one result object.
child_process.spawnSync() starts a program, waits for it to finish, and returns everything about the run in one object: exit status, terminating signal, captured output, and an error if the process could not be started or timed out. The whole event loop is blocked while it waits, so nothing else in your program runs.
It is the right tool for command-line scripts, build tools and start-up checks, where waiting is the point. In a server handling concurrent requests, use the asynchronous spawn() or execFile() instead.
import { spawnSync } from 'node:child_process'; const result = spawnSync('node', ['--version'], { encoding: 'utf8' }); console.log(result.status, result.stdout);
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
child_process.spawnSync(command[, args][, options]) // returns { pid, output, stdout, stderr, status, signal, error }
| Name | Description |
|---|---|
command |
The program to run. Without shell it is looked up on PATH and run directly. |
args |
Array of string arguments. Not parsed by a shell, so spaces and quotes inside an element stay as they are. |
options.cwd, env, argv0, uid, gid |
Same as for spawn(). |
options.input |
A string, Buffer, TypedArray or DataView written to the child's stdin. When given, it overrides stdio[0]. |
options.stdio |
'pipe' (default) for all three streams, or an array. See stdio options. |
options.encoding |
'buffer' by default, so stdout and stderr are Buffer objects. Set 'utf8' for strings. |
options.timeout |
Milliseconds before the child is killed with killSignal. Default: no limit. |
options.killSignal |
Signal used for timeouts and maxBuffer overflow. Default 'SIGTERM'. |
options.maxBuffer |
Largest amount of data, in bytes, allowed on stdout or stderr. Default 1 MiB. |
options.shell |
true or a shell path to run command through a shell. Risky with user input. |
options.windowsHide |
Hide the console window on Windows. |
Returns: an object with these properties:
pid: process id (0 if the process never started).status: the exit code, ornullif the process was ended by a signal.signal: the signal name, ornullif the process exited normally.output: array[stdin, stdout, stderr]of the captured streams (the first entry isnull).stdout,stderr: the captured output (nullfor streams that were not piped).error: anErrorif the process failed to spawn, timed out (ETIMEDOUT) or exceededmaxBuffer(ENOBUFS); otherwiseundefined.
Errors: invalid arguments throw synchronously (ERR_INVALID_ARG_TYPE). A non-zero exit code does not throw; check result.status.
Usage notes
- It never throws for a failing program. Always inspect
status,signalanderror. A common bug is checking onlystatus: a missing program givesstatus === nulland a populatederror. - Output is Buffers by default. Pass
encoding: 'utf8'to get strings, otherwiseresult.stdout + ''is the quick (and implicit) conversion. - On timeout or overflow the child is killed with
killSignal, andresult.erroris set. Output captured until that moment is still instdout, but it may be cut off. - The parent is blocked. Timers, I/O and other requests wait. Never call it on a hot server path.
stdio: 'inherit'makesstdoutandstderrnull. The child writes straight to your terminal and nothing is captured.- A shell is optional. Without
shellthere is no globbing, no pipes and no$VARIABLES; this is also what makes it safe. See shell injection. - Closely related:
execSync()runs a command line through a shell, returns only stdout, and throws on failure. - Windows:
.cmdand.batfiles cannot be started without a shell. Native executables such asprocess.execPathwork everywhere.