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().
import { execSync } from 'node:child_process'; const output = execSync('echo hello', { encoding: 'utf8' }); console.log(output.trim()); // hello
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.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
stdioexplicitly and capture it another way, or to usespawnSync(), which returns both. - Failure is an exception. Wrap calls in
try/catch. The thrownerror.stdoutanderror.stderrhold what the command printed before it failed, and are Buffers unless you setencoding. - 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 untiltimeout). - Injection risk.
execSync(`ls ${userInput}`)lets a visitor run any command. Pass untrusted values as separate arguments tospawnSync()without a shell. - Shell syntax differs per platform. A command that works in
shmay fail incmd.exe. For portable scripts, runprocess.execPathwith 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.