Execute a command line binary with Node.js
Solution 1
For even newer version of Node.js (v8.1.4), the events and calls are similar or identical to older versions, but it's encouraged to use the standard newer language features. Examples:
For buffered, non-stream formatted output (you get it all at once), use child_process.exec
:
const { exec } = require('child_process');
exec('cat *.js bad_file | wc -l', (err, stdout, stderr) => {
if (err) {
// node couldn't execute the command
return;
}
// the *entire* stdout and stderr (buffered)
console.log(`stdout: ${stdout}`);
console.log(`stderr: ${stderr}`);
});
You can also use it with Promises:
const util = require('util');
const exec = util.promisify(require('child_process').exec);
async function ls() {
const { stdout, stderr } = await exec('ls');
console.log('stdout:', stdout);
console.log('stderr:', stderr);
}
ls();
If you wish to receive the data gradually in chunks (output as a stream), use child_process.spawn
:
const { spawn } = require('child_process');
const child = spawn('ls', ['-lh', '/usr']);
// use child.stdout.setEncoding('utf8'); if you want text chunks
child.stdout.on('data', (chunk) => {
// data from standard output is here as buffers
});
// since these are streams, you can pipe them elsewhere
child.stderr.pipe(dest);
child.on('close', (code) => {
console.log(`child process exited with code ${code}`);
});
Both of these functions have a synchronous counterpart. An example for child_process.execSync
:
const { execSync } = require('child_process');
// stderr is sent to stderr of parent process
// you can set options.stdio if you want it to go elsewhere
let stdout = execSync('ls');
As well as child_process.spawnSync
:
const { spawnSync} = require('child_process');
const child = spawnSync('ls', ['-lh', '/usr']);
console.log('error', child.error);
console.log('stdout ', child.stdout);
console.log('stderr ', child.stderr);
Note: The following code is still functional, but is primarily targeted at users of ES5 and before.
The module for spawning child processes with Node.js is well documented in the documentation (v5.0.0). To execute a command and fetch its complete output as a buffer, use child_process.exec
:
var exec = require('child_process').exec;
var cmd = 'prince -v builds/pdf/book.html -o builds/pdf/book.pdf';
exec(cmd, function(error, stdout, stderr) {
// command output is in stdout
});
If you need to use handle process I/O with streams, such as when you are expecting large amounts of output, use child_process.spawn
:
var spawn = require('child_process').spawn;
var child = spawn('prince', [
'-v', 'builds/pdf/book.html',
'-o', 'builds/pdf/book.pdf'
]);
child.stdout.on('data', function(chunk) {
// output will be here in chunks
});
// or if you want to send output elsewhere
child.stdout.pipe(dest);
If you are executing a file rather than a command, you might want to use child_process.execFile
, which parameters which are almost identical to spawn
, but has a fourth callback parameter like exec
for retrieving output buffers. That might look a bit like this:
var execFile = require('child_process').execFile;
execFile(file, args, options, function(error, stdout, stderr) {
// command output is in stdout
});
As of v0.11.12, Node now supports synchronous spawn
and exec
. All of the methods described above are asynchronous, and have a synchronous counterpart. Documentation for them can be found here. While they are useful for scripting, do note that unlike the methods used to spawn child processes asynchronously, the synchronous methods do not return an instance of ChildProcess
.
Solution 2
Node JS v15.8.0
, LTS v14.15.4
, and v12.20.1
--- Feb 2021
Async method (Unix):
'use strict';
const { spawn } = require( 'child_process' );
const ls = spawn( 'ls', [ '-lh', '/usr' ] );
ls.stdout.on( 'data', ( data ) => {
console.log( `stdout: ${ data }` );
} );
ls.stderr.on( 'data', ( data ) => {
console.log( `stderr: ${ data }` );
} );
ls.on( 'close', ( code ) => {
console.log( `child process exited with code ${ code }` );
} );
Async method (Windows):
'use strict';
const { spawn } = require( 'child_process' );
// NOTE: Windows Users, this command appears to be differ for a few users.
// You can think of this as using Node to execute things in your Command Prompt.
// If `cmd` works there, it should work here.
// If you have an issue, try `dir`:
// const dir = spawn( 'dir', [ '.' ] );
const dir = spawn( 'cmd', [ '/c', 'dir' ] );
dir.stdout.on( 'data', ( data ) => console.log( `stdout: ${ data }` ) );
dir.stderr.on( 'data', ( data ) => console.log( `stderr: ${ data }` ) );
dir.on( 'close', ( code ) => console.log( `child process exited with code ${code}` ) );
Sync:
'use strict';
const { spawnSync } = require( 'child_process' );
const ls = spawnSync( 'ls', [ '-lh', '/usr' ] );
console.log( `stderr: ${ ls.stderr.toString() }` );
console.log( `stdout: ${ ls.stdout.toString() }` );
From Node.js v15.8.0 Documentation
The same goes for Node.js v14.15.4 Documentation and Node.js v12.20.1 Documentation
Solution 3
You are looking for child_process.exec
Here is the example:
const exec = require('child_process').exec;
const child = exec('cat *.js bad_file | wc -l',
(error, stdout, stderr) => {
console.log(`stdout: ${stdout}`);
console.log(`stderr: ${stderr}`);
if (error !== null) {
console.log(`exec error: ${error}`);
}
});
Solution 4
Since version 4 the closest alternative is child_process.execSync
method:
const {execSync} = require('child_process');
let output = execSync('prince -v builds/pdf/book.html -o builds/pdf/book.pdf');
⚠️ Note that
execSync
call blocks event loop.
Solution 5
const exec = require("child_process").exec
exec("ls", (error, stdout, stderr) => {
//do whatever here
})
Dave Thompson
I'm a web/web-app designer/programmer by trade, a writer, and founder of BlueHead Publishing, a company focused on providing agile software and tools for the book publishing industry. I'm alsoa musician (piano/vocal - it's good creative fun for the soul).
Updated on July 08, 2022Comments
-
Dave Thompson almost 2 years
I am in the process of porting a CLI library from Ruby over to Node.js. In my code I execute several third party binaries when necessary. I am not sure how best to accomplish this in Node.
Here's an example in Ruby where I call PrinceXML to convert a file to a PDF:
cmd = system("prince -v builds/pdf/book.html -o builds/pdf/book.pdf")
What is the equivalent code in Node?
-
hgoebl over 10 yearsThis is correct. But be aware that this kind of calling a child-process has limitations for the length of stdout.
-
Dave Thompson over 10 yearsTHANK YOU. This was driving me nuts. Sometimes it helps to just have the obvious solution pointed out so we noobs (to node) can learn and run with it.
-
Louis Ameline about 10 yearsNote : require('child_process').execFile() will be of interest for people who need to run a file rather than a system-wide known command like prince here.
-
Vadorequest about 9 yearsMost recent version there, with usage example to use Grunt in CLI: gist.github.com/Vadorequest/f72fa1c152ec55357839
-
ComFreek over 8 yearsInstead of
child.pipe(dest)
(which doesn't exist), you have to usechild.stdout.pipe(dest)
andchild.stderr.pipe(dest)
, e.g.child.stdout.pipe(process.stdout)
andchild.stderr.pipe(process.stderr)
. -
Harshdeep over 8 years@hgoebl, what is the alternative then?
-
hgoebl over 8 years@Harshdeep in case of long stdout outputs (several MB e.g.) you can listen to
data
events on stdout. Look in the docs, but it must be something likechildProc.stdout.on("data", fn)
. -
NiCk Newman almost 8 yearsThis works great on latest node. Is a
child_process
being created when usingexecSync
though? And does it get removed right after the command, right? So no memory leaks? -
Paul Rumkin almost 8 yearsYes, there is no memory leaks. I guess it initialises only libuv child process structures without creating it in node at all.
-
Brian Jorden about 7 yearsThank you for giving both proper and simple versions. The slightly simpler sync version was totally fine for my one off "do something and throw it away" script that I needed.
-
iSkore about 7 yearsNo problem! Always nice to have both even if it's not "proper" according to some.
-
Al Sweigart about 7 yearsPlease add more explanation for how this code works and how it solves the answer. Remember that StackOverflow is building an archive of answers for people reading this in the future.
-
Cameron almost 7 yearsWhat if I don't want to put everything into a file, but I want to execute more than one command? Maybe like
echo "hello"
andecho "world"
. -
Rishabh Agrawal over 6 yearsis this the standard way to do this ? i mean how all the wrapper are written in nodejs ? i mean let's say for gearman,rabbitmq etc. which require to run the command but they also have some wrapper as well but i can't find any of this code in their library code
-
Mathankumar K over 6 years@hexacyanide . any possible to open
c:windows\system32\osk.exe
form child process options. -
AndyO about 6 yearsMight be worth pointing out that in order to do this example in Windows, one has to use
'cmd', ['/c', 'dir']
. At least I was just searching high and low why'dir'
without arguments doesn't work before I remembered this... ;) -
Tyguy7 over 5 yearsNone of these output ANYTHING to the console.
-
iSkore over 5 years@Tyguy7 how are you running it? And do you have any overrides on the console object?
-
Admin over 5 yearsWhat Al said is true, but I will say the benefit of this answer is that it is so much simpler than having to read through the top answer for someone who needs a quick response.
-
Stephen over 5 yearsWhy do you claim one method is proper?
-
iSkore over 5 yearsI’m assuming you are reffering to why async is proper? Because of how the event loop works with synchronous functions. Synchronous functions will stop all other executions until the synchronous function is complete. For instance, let’s say you’re running a server that accepts HTTP requests that dispatch a synchronous CLI command. Let’s say an ffmpeg command that could take minutes or more. All other requests would be completely blocked until that original request is fulfilled. All recommendations in the node spec recommend using async, for that reason I specify “proper”
-
iSkore over 5 yearsBut I added the synchronous method example because its still valid and in testing senarios or during a programs “initialization” stage, when the program first starts, and never runs those commands again, synchronous methods are a valid use case. But during standard runtime of a program, synchronous methods are not advised.
-
Nouman Dilshad over 5 years@iSkore I am executing a command using ('child_process').exec but it gives me an error Error: Command failed: unoconv -f pdf "./document.docx" 'unoconv' is not recognized as an internal or external command, operable program or batch file. This command is working when I run it in git commandline tool.
-
iSkore over 5 yearsSounds like you are running on a windows machine (if you have a “git CLI tool) and the unoconv tool isn’t installed. Try running that unoconv command in your powershell. If it doesn’t run there, it won’t run in node. This answer is the “general use case” so try running the
dir
orls
command. If that doesn’t work the function is setup incorrectly. -
Lindsay Ryan almost 5 yearsMay I suggest adding a short explanation to the top of this clarifying that
async
is what's meant by proper? In the context of the other responses, my first understanding was conversely thatspawn
was more proper than the other alternatives, such asexec
. Especially since you say "From the documentation". This gives the impression that the documentation advises usingspawn
over alternatives, when the documentation actually highlights thatspawn
is the underlying mechanism for all the others. -
OhadR about 4 yearssuper silly question: what is the meaning of declaring const { spawnSync } (what is the meaning of the curly braces around 'spawnSync ' ?)
-
iSkore about 4 yearsNot a silly question at all! here’s a resource for you - object destructuring is a way to extract a key from an object. Like this:
const { a, b } = { a: 10, b: 20 }
is the same asconst a = obj.a, b = obj.b;
-
iSkore about 4 yearsIt only imports what you want opposed to a reference to the entire module
-
roosevelt about 4 yearsPerfect! Works great for my needs.
-
Ben Bieler almost 4 yearsIt should not be necessary to install new modules
-
Cam Jackson over 2 yearsNote that if you want all of the child's input and output to just be passed straight through, then you can call spawn like this:
spawn('ls', { stdio: 'inherit' })
. That way you don't have to stuff around withchild.stdout.on('data'...
and all the rest of it.