Node.js Reference ยท child_process, worker_threads and cluster
Node.js child_process.execFile() method
Reference for child_process.execFile() in Node.js: run a program with an argument array and no shell, buffer its output, handle errors, timeouts and maxBuffer safely.
child_process.execFile() runs a program directly, with no shell in between, and delivers its buffered output when it finishes. You give it the file to run and an array of arguments; each array element reaches the program as exactly one argument, with no splitting on spaces, no wildcard expansion and no interpretation of characters like ;, | or $. That is why it is the safe default for running a known program with values that may come from users.
Like exec(), it collects stdout and stderr in memory (capped by maxBuffer) and calls back once. Unlike exec(), it does not support shell syntax such as pipes or redirection unless you opt in with the shell option.
import { execFile } from 'node:child_process'; execFile(process.execPath, ['--version'], (error, stdout) => { console.log(stdout.trim()); });
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.execFile(file: string, args?: string[], options?: object, callback?: (error: Error | null, stdout: string | Buffer, stderr: string | Buffer) => void): ChildProcess
| Name | Description |
|---|---|
file |
The name or path of the program. Searched on PATH if it has no path separator. |
args |
List of arguments, passed through unchanged. |
options.cwd, options.env |
Working directory and environment of the child. |
options.encoding |
Output encoding. Default 'utf8'; 'buffer' returns Buffers. |
options.timeout |
Kill the child after this many milliseconds. Default 0 (none). |
options.maxBuffer |
Largest allowed size of stdout or stderr. Default 1048576 bytes. |
options.killSignal |
Signal used on timeout or when maxBuffer is exceeded. Default 'SIGTERM'. |
options.shell |
true or a shell path to run file through a shell. Default false. |
options.signal |
An AbortSignal that cancels the run. |
options.windowsVerbatimArguments |
Do not quote or escape arguments on Windows. Default false. |
Returns: a ChildProcess. With util.promisify() the promise resolves to { stdout, stderr }.
Errors: error is null when the program exits with status 0. Otherwise it carries code (the exit status, or a string like ENOENT or ERR_CHILD_PROCESS_STDIO_MAXBUFFER), killed, signal, cmd and the buffered stdout and stderr.
Usage notes
- Prefer
execFile()overexec()whenever the program is known in advance. Arguments cannot be turned into extra commands, so classic shell injection is impossible (a program that itself treats an argument as a command, likesh -c, can still be abused). - Arguments starting with
-may be read as options by the program. When passing user data, put it after a--separator if the program supports it. - Because there is no shell, there is no glob expansion,
~expansion or environment variable substitution inside arguments. Do these in JavaScript. - On Windows,
.cmdand.batfiles are not executables and fail withEINVAL(since a 2024 security fix) unless you passshell: true. Real.exefiles work normally. - Use
process.execPathto run the same Node.js binary as the parent. - Output is buffered and capped. For long-running programs or large output use spawn(), which streams.
- If you pass
shell: true, the arguments are joined into a command string without escaping, and the injection protection is gone; see Shell injection.