Skip to content
Tutorials Center
My learning

Topics

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.

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

const result = spawnSync('node', ['--version'], { encoding: 'utf8' });
console.log(result.status, result.stdout);

Try it

Node.js Reading the result object

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 Input, timeouts and start-up failures

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
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, or null if the process was ended by a signal.
  • signal: the signal name, or null if the process exited normally.
  • output: array [stdin, stdout, stderr] of the captured streams (the first entry is null).
  • stdout, stderr: the captured output (null for streams that were not piped).
  • error: an Error if the process failed to spawn, timed out (ETIMEDOUT) or exceeded maxBuffer (ENOBUFS); otherwise undefined.

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, signal and error. A common bug is checking only status: a missing program gives status === null and a populated error.
  • Output is Buffers by default. Pass encoding: 'utf8' to get strings, otherwise result.stdout + '' is the quick (and implicit) conversion.
  • On timeout or overflow the child is killed with killSignal, and result.error is set. Output captured until that moment is still in stdout, 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' makes stdout and stderr null. The child writes straight to your terminal and nothing is captured.
  • A shell is optional. Without shell there 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: .cmd and .bat files cannot be started without a shell. Native executables such as process.execPath work everywhere.