# promisify-child-process

> seriously like the best async child process library

Latest version **5.0.1** (published 2026-02-04) · MIT license · 0 weekly downloads

## Install

```sh
npm install promisify-child-process
pnpm add promisify-child-process
yarn add promisify-child-process
bun add promisify-child-process
```

## Health

**Score 55/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 5.0.1 |
| Published | 2026-02-04 |
| First published | 2017-12-06 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=16 |
| Dependencies | 1 |
| Unpacked size | 59.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 63 |
| Author | Andy Edwards |
| Maintainers | jedwards1211 |
| Keywords | child, process, child_process, exec, spawn, execFile, fork, promise, promises, async, await, thenable |

## Links

- npm: https://www.npmjs.com/package/promisify-child-process
- Repository: https://github.com/jcoreio/promisify-child-process
- Homepage: https://github.com/jcoreio/promisify-child-process#readme
- Issues: https://github.com/jcoreio/promisify-child-process/issues
- npm.io page: https://npm.io/package/promisify-child-process

## Dependencies (1)

- [@babel/runtime](https://npm.io/package/@babel/runtime.md) ^7.26.0

## Alternatives

- [@commercetools/sync-actions](https://npm.io/package/@commercetools/sync-actions.md) — 25.1K weekly downloads
- [cwait](https://npm.io/package/cwait.md) — 21.4K weekly downloads
- [@ledgerhq/hw-app-cosmos](https://npm.io/package/@ledgerhq/hw-app-cosmos.md) — 4.2K weekly downloads
- [@financial-times/o-loading](https://npm.io/package/@financial-times/o-loading.md) — 2.8K weekly downloads
- [fa](https://npm.io/package/fa.md) — 185 weekly downloads

## Recent versions

- 5.0.1 (latest) — 2026-02-04
- 5.0.0 — 2026-02-03
- 4.1.2 — 2023-07-10
- 4.1.1 — 2020-05-17
- 4.1.0 — 2020-05-08
- 4.0.2 — 2020-05-08
- 4.0.1 — 2020-05-05
- 4.0.0 — 2020-05-05
- 4.0.0-rc.0 — 2020-05-05
- 3.1.4 — 2020-03-19
- 3.1.3 — 2019-12-12
- 3.1.2 — 2019-12-11
- 3.1.1 — 2019-07-09
- 3.1.0 — 2018-11-27
- 3.0.1 — 2018-11-26
- … 11 more at https://npm.io/package/promisify-child-process/versions

## README

# promisify-child-process

[![CircleCI](https://circleci.com/gh/jcoreio/promisify-child-process.svg?style=svg)](https://circleci.com/gh/jcoreio/promisify-child-process)
[![Coverage Status](https://codecov.io/gh/jcoreio/promisify-child-process/branch/master/graph/badge.svg)](https://codecov.io/gh/jcoreio/promisify-child-process)
[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)
[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)
[![npm version](https://badge.fury.io/js/promisify-child-process.svg)](https://badge.fury.io/js/promisify-child-process)

seriously like the best async child process library

(I'm joking, you may want to use [`execa`](https://github.com/sindresorhus/execa) which has a lot more features. The minor advantages of this package are:)

- it's a dual CJS/ESM package
- it conforms to the `child_process` API
- and it provides wrappers for all the async `child_process` functions

Based upon [`child-process-async`](https://github.com/itsjustcon/node-child-process-async),
but more thorough, because that package doesn't seem very actively maintained.

`promisify-child-process` provides a **drop-in replacement** for the
original `child_process` functions, not just duplicate methods that
return a `Promise`. So when you call `exec(...)` we still return a
`ChildProcess` instance, just with `.then()`, `.catch()`, and `.finally()` added to
make it promise-friendly.

## Install and Set-up

```sh
npm install --save promisify-child-process
```

If you are using a old version of Node without built-in `Promise`s or
`Object.create`, you will need to use polyfills (e.g. `@babel/polyfill`).

```js
// OLD:
const { exec, spawn, fork, execFile } = require('child_process')
// NEW:
const { exec, spawn, fork, execFile } = require('promisify-child-process')
```

## Upgrading to v3

You must now pass `maxBuffer` or `encoding` to `spawn`/`fork` if you want to
capture `stdout` or `stderr`.

## Resolution/Rejection

The child process promise will only resolve if the process exits with a code of 0.
If it exits with any other code, is killed by a signal, or emits an `'error'` event,
the promise will reject.

## Capturing output

`exec` and `execFile` capture `stdout` and `stderr` by default. But `spawn` and
`fork` don't capture `stdout` and `stderr` unless you pass an `encoding` or
`maxBuffer` option:

```js
const { spawn } = require('promisify-child-process');

async function() {
  // captures output
  const { stdout, stderr } = await spawn('ls', [ '-al' ], {encoding: 'utf8'});
  const { stdout, stderr } = await spawn('ls', [ '-al' ], {maxBuffer: 200 * 1024});

  // BUG, DOESN'T CAPTURE OUTPUT:
  const { stdout, stderr } = await spawn('ls', [ '-al' ]);
}
```

## Additional properties on rejection errors

If the child process promise rejects, the error may have the following additional
properties:

- `code` - the process' exit code (if it exited)
- `signal` - the signal the process was killed with (if it was killed)
- `stdout` - the captured `stdout` (if output capturing was enabled)
- `stderr` - the captured `stderr` (if output capturing was enabled)

## Wrapper

If for any reason you need to wrap a `ChildProcess` you didn't create,
you can use the exported `promisifyChildProcess` function:

```js
const { promisifyChildProcess } = require('promisify-child-process');

async function() {
  const { stdout, stderr } = await promisifyChildProcess(
    some3rdPartyFunctionThatReturnsChildProcess(),
    { encoding: 'utf8' }
  )
}
```

## Examples

### `exec()`

```js
async function() {
  const { stdout, stderr } = await exec('ls -al');
  // OR:
  const child = exec('ls -al', {});
  // do whatever you want with `child` here - it's a ChildProcess instance just
  // with promise-friendly `.then()` & `.catch()` functions added to it!
  child.stdin.write(...);
  child.stdout.pipe(...);
  child.stderr.on('data', (data) => ...);
  const { stdout, stderr } = await child;
}
```

### `spawn()`

```js
async function() {
  const { stdout, stderr, code } = await spawn('ls', [ '-al' ], {encoding: 'utf8'});
  // OR:
  const child = spawn('ls', [ '-al' ], {});
  // do whatever you want with `child` here - it's a ChildProcess instance just
  // with promise-friendly `.then()` & `.catch()` functions added to it!
  child.stdin.write(...);
  child.stdout.pipe(...);
  child.stderr.on('data', (data) => ...);
  const { stdout, stderr, code } = await child;
}
```

---
_Source: https://npm.io/package/promisify-child-process · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._