A better `child_process`
Latest commit 863e4a7 Jan 21, 2017 @sindresorhus Add a tip to the readme
Closes #64


execa Build Status: Linux Build status: Windows Coverage Status

A better child_process



$ npm install --save execa


const execa = require('execa');

execa('echo', ['unicorns']).then(result => {
    //=> 'unicorns'

// pipe the child process stdout to the current stdout
execa('echo', ['unicorns']).stdout.pipe(process.stdout);

execa.shell('echo unicorns').then(result => {
    //=> 'unicorns'

// example of catching an error
execa.shell('exit 3').catch(error => {
        message: 'Command failed: /bin/sh -c exit 3'
        killed: false,
        code: 3,
        signal: null,
        cmd: '/bin/sh -c exit 3',
        stdout: '',
        stderr: '',
        timedOut: false


execa(file, [arguments], [options])

Execute a file.

Same options as child_process.execFile.

Think of this as a mix of child_process.execFile and child_process.spawn.

Returns a child_process instance, which is enhanced to also be a Promise for a result Object with stdout and stderr properties.

execa.stdout(file, [arguments], [options])

Same as execa(), but returns only stdout.

execa.stderr(file, [arguments], [options])

Same as execa(), but returns only stderr.

execa.shell(command, [options])

Execute a command through the system shell. Prefer execa() whenever possible, as it's both faster and safer.

Same options as child_process.exec.

Returns a child_process instance.

The child_process instance is enhanced to also be promise for a result object with stdout and stderr properties.

execa.sync(file, [arguments], [options])

Execute a file synchronously.

Same options as child_process.execFileSync, except the default encoding is utf8 instead of buffer.

Returns the same result object as child_process.spawnSync.

This method throws an Error if the command fails.

execa.shellSync(file, [options])

Execute a command synchronously through the system shell.

Same options as child_process.execSync, except the default encoding is utf8 instead of buffer.

Returns the same result object as child_process.spawnSync.


Additional options:


Type: boolean
Default: true

Strip EOF (last newline) from the output.


Type: boolean
Default: true

Prefer locally installed binaries when looking for a binary to execute.
If you $ npm install foo, you can then execa('foo').


Type: string Buffer ReadableStream

Write some input to the stdin of your binary.
Streams are not allowed when using the synchronous methods.


Type: boolean
Default: true

Setting this to false resolves the promise with the error instead of rejecting it.


Type: boolean
Default: true

Keep track of the spawned process and kill it when the parent process exits.


Save and pipe output from a child process

Let's say you want to show the output of a child process in real-time while also saving it to a variable.

const execa = require('execa');
const getStream = require('get-stream');

const stream = execa('echo', ['foo']).stdout;


getStream(stream).then(value => {
    console.log('child output:', value);


MIT © Sindre Sorhus