Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท child_process, worker_threads and cluster

Node.js child_process.execSync() method

Reference for child_process.execSync() in Node.js: run a shell command, wait for it, get stdout back, and handle the error thrown on a non-zero exit code.

child_process.execSync() runs a command line through the system shell, blocks until it finishes, and returns its standard output. If the command exits with a non-zero code, is killed by a signal or times out, execSync() throws an error that carries the status, signal and captured output.

Because it uses a shell, pipes, redirects, globs and environment variables work as you would type them in a terminal. That convenience is also the danger: never build the command string from untrusted input. See shell injection. For commands that take arguments from variables, prefer execFileSync() or spawnSync().

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

const output = execSync('echo hello', { encoding: 'utf8' });
console.log(output.trim()); // hello

Try it

Node.js Output, pipes and encoding

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 What a failing command throws

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.execSync(command[, options])
// returns Buffer | string (the command's stdout)
Name Description
command The full command line, interpreted by the shell.
options.cwd, env, uid, gid Same as for spawn().
options.input String, Buffer, TypedArray or DataView written to the command's stdin.
options.stdio Defaults to 'pipe', but the child's stderr is also forwarded to the parent's stderr unless you set stdio yourself.
options.encoding 'buffer' by default. Use 'utf8' for a string.
options.shell Path of the shell to use. Default /bin/sh on Unix, process.env.ComSpec on Windows.
options.timeout Milliseconds before the command is killed. Default: none.
options.killSignal Signal sent on timeout or when maxBuffer is exceeded. Default 'SIGTERM'.
options.maxBuffer Largest amount of output in bytes. Default 1 MiB.
options.windowsHide Hide the console window on Windows.

Returns: the standard output of the command, as a Buffer or, with encoding, a string.

Errors: an Error is thrown when the exit code is not 0, when a signal ends the command, on timeout (code: 'ETIMEDOUT') and when the output exceeds maxBuffer (code: 'ENOBUFS'). The error has status, signal, stdout, stderr, pid and output, and its message starts with Command failed: followed by the command and the stderr text.

Usage notes

  • Only stdout is returned. The only way to read stderr on success is to give stdio explicitly and capture it another way, or to use spawnSync(), which returns both.
  • Failure is an exception. Wrap calls in try/catch. The thrown error.stdout and error.stderr hold what the command printed before it failed, and are Buffers unless you set encoding.
  • Output usually ends with a newline. Call .trim() before comparing or parsing.
  • Blocks everything. Timers and I/O wait until the command ends. Use exec() in servers, and never run commands that wait for terminal input (they hang until timeout).
  • Injection risk. execSync(`ls ${userInput}`) lets a visitor run any command. Pass untrusted values as separate arguments to spawnSync() without a shell.
  • Shell syntax differs per platform. A command that works in sh may fail in cmd.exe. For portable scripts, run process.execPath with its own arguments instead of shell tools.
  • A forgotten stdio: 'pipe' is noisy. Without it, a failing command's stderr appears in your own terminal as well as in the thrown error.