# pidtree

> Cross platform children list of a PID

Latest version **1.0.0** (published 2026-06-08) · MIT license · 0 weekly downloads

## Install

```sh
npm install pidtree
pnpm add pidtree
yarn add pidtree
bun add pidtree
```

Provides the command `pidtree`.

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.0.0 |
| Published | 2026-06-08 |
| First published | 2018-03-19 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18 |
| Dependencies | 0 |
| Unpacked size | 24.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 127 |
| Author | Simone Primarosa |
| Maintainers | simonepri |
| Keywords | ps-tree, ps, tree, ppid, pid, pidtree, pgrep, list, all, system, process, processes |

## Links

- npm: https://www.npmjs.com/package/pidtree
- Repository: https://github.com/simonepri/pidtree
- Homepage: http://github.com/simonepri/pidtree#readme
- Issues: https://github.com/simonepri/pidtree/issues
- npm.io page: https://npm.io/package/pidtree

## Alternatives

- [@sindresorhus/slugify](https://npm.io/package/@sindresorhus/slugify.md) — 3.7M weekly downloads
- [solid-js](https://npm.io/package/solid-js.md) — 2.7M weekly downloads
- [expo-glass-effect](https://npm.io/package/expo-glass-effect.md) — 2.5M weekly downloads
- [nanoassert](https://npm.io/package/nanoassert.md) — 780.8K weekly downloads
- [@ffmpeg/ffmpeg](https://npm.io/package/@ffmpeg/ffmpeg.md) — 529.5K weekly downloads

## Recent versions

- 1.0.0 (latest) — 2026-06-08
- 0.6.1 — 2026-06-08
- 0.6.0 — 2022-06-05
- 0.5.0 — 2020-04-13
- 0.4.0 — 2020-03-26
- 0.3.1 — 2020-03-26
- 0.3.0 — 2018-03-20
- 0.2.0 — 2018-03-19
- 0.1.4 — 2018-03-19
- 0.1.3 — 2018-03-19
- 0.1.2 — 2018-03-19
- 0.1.1 — 2018-03-19

## README

<h1 align="center">
  <b>pidtree</b>
</h1>
<p align="center">
  <!-- Version - npm -->
  <a href="https://www.npmjs.com/package/pidtree">
    <img src="https://img.shields.io/npm/v/pidtree.svg" alt="Latest version on npm" />
  </a>
  <!-- Downloads - npm -->
  <a href="https://npm-stat.com/charts.html?package=pidtree">
    <img src="https://img.shields.io/npm/dt/pidtree.svg" alt="Downloads on npm" />
  </a>
  <!-- License - MIT -->
  <a href="https://github.com/simonepri/pidtree/tree/master/license">
    <img src="https://img.shields.io/github/license/simonepri/pidtree.svg" alt="Project license" />
  </a>

  <br/>

  <!-- Lint -->
  <a href="https://github.com/simonepri/pidtree/actions?query=workflow:lint+branch:master">
    <img src="https://github.com/simonepri/pidtree/workflows/lint/badge.svg?branch=master" alt="Lint status" />
  </a>
  <!-- Test - macOS -->
  <a href="https://github.com/simonepri/pidtree/actions?query=workflow:test-macos+branch:master">
    <img src="https://github.com/simonepri/pidtree/workflows/test-macos/badge.svg?branch=master" alt="Test macOS status" />
  </a>
  <!-- Test - Ubuntu -->
  <a href="https://github.com/simonepri/pidtree/actions?query=workflow:test-ubuntu+branch:master">
    <img src="https://github.com/simonepri/pidtree/workflows/test-ubuntu/badge.svg?branch=master" alt="Test Ubuntu status" />
  </a>
  <!-- Test - Windows -->
  <a href="https://github.com/simonepri/pidtree/actions?query=workflow:test-windows+branch:master">
    <img src="https://github.com/simonepri/pidtree/workflows/test-windows/badge.svg?branch=master" alt="Test Windows status" />
  </a>
  <!-- Coverage - Codecov -->
  <a href="https://codecov.io/gh/simonepri/pidtree">
    <img src="https://img.shields.io/codecov/c/github/simonepri/pidtree/master.svg" alt="Codecov Coverage report" />
  </a>
  <!-- DM - Snyk -->
  <a href="https://snyk.io/test/github/simonepri/pidtree?targetFile=package.json">
    <img src="https://snyk.io/test/github/simonepri/pidtree/badge.svg?targetFile=package.json" alt="Known Vulnerabilities" />
  </a>

  <br/>

  <!-- Code Style - XO-Prettier -->
  <a href="https://github.com/xojs/xo">
    <img src="https://img.shields.io/badge/code_style-XO+Prettier-5ed9c7.svg" alt="XO Code Style used" />
  </a>
  <!-- Test Runner - AVA -->
  <a href="https://github.com/avajs/ava">
    <img src="https://img.shields.io/badge/test_runner-AVA-fb3170.svg" alt="AVA Test Runner used" />
  </a>
  <!-- Test Coverage - c8 -->
  <a href="https://github.com/bcoe/c8">
    <img src="https://img.shields.io/badge/test_coverage-c8-fec606.svg" alt="c8 Test Coverage used" />
  </a>
  <!-- Init - ni -->
  <a href="https://github.com/simonepri/ni">
    <img src="https://img.shields.io/badge/initialized_with-ni-e74c3c.svg" alt="NI Scaffolding System used" />
  </a>
  <!-- Release - release-please -->
  <a href="https://github.com/googleapis/release-please">
    <img src="https://img.shields.io/badge/released_with-release--please-6c8784.svg" alt="release-please Release System used" />
  </a>
</p>
<p align="center">
  🚸 Cross platform children list of a PID.

  <br/>

  <sub>
    Coded with ❤️ by <a href="#authors">Simone Primarosa</a>.
  </sub>
</p>

## Synopsis

This package is really similar to [ps-tree][gh:ps-tree] but is faster, safer and
provides sub-children results.  
Furthermore ps-tree is [unmaintained][gh:ps-tree-um].

Uuh, and a fancy [CLI](#cli) is also available!

## Install

```bash
npm install pidtree
```

> **Requirements:** pidtree is an [ESM-only][gh:esm] package and requires
> **Node.js >= 18**. If you need CommonJS (`require`) or support for older
> Node.js versions, stay on [`pidtree@0.6`](https://www.npmjs.com/package/pidtree/v/0.6.1).

## Usage

```js
import pidtree from 'pidtree'
// The named import works too: import {pidtree} from 'pidtree'

// Get children of the current process (a promise is returned)
const pids = await pidtree(process.pid)
console.log(pids)
// => []

// Include the given pid in the result array
console.log(await pidtree(process.pid, {root: true}))
// => [727]

// Get all the processes of the System (-1 is a special value of this package)
console.log(await pidtree(-1))
// => [530, 42, ..., 41241]

// Include the PPID in the results
console.log(await pidtree(1, {advanced: true}))
// => [{ppid: 1, pid: 530}, {ppid: 1, pid: 42}, ..., {ppid: 1, pid: 41241}]

// A Node-style callback is also supported instead of a promise
pidtree(1, function (err, pids) {
  console.log(pids)
  // => [141, 42, ..., 15242]
})
```

## Compatibility

| Linux | FreeBSD | NetBSD | SunOS | macOS | Win | AIX |
| --- | --- | --- | --- | --- | --- | --- |
| ✅ | ❓ | ❓ | ❓ | ✅ | ✅ | ❓ |

✅ = Working
❓ = Not tested but should work

Please if your platform is not supported [file an issue][new issue].

## CLI

<img src="https://github.com/simonepri/pidtree/raw/master/media/cli.gif" alt="pidtree cli" width="300" align="right"/>
Show a tree of the processes inside your system inside your terminal.

```bash
npx pidtree $PPID
```
Just replace `$PPID` with one of the pids inside your system.

Or don't pass anything if you want all the pids inside your system.

```bash
npx pidtree
```

To display the output as a list, similar to the one produced from `pgrep -P $PID`,
pass the `--list` flag.

```bash
npx pidtree --list
```

## API

<a name="pidtree"></a>

## pidtree(pid, [options], [callback]) ⇒ <code>[Promise.&lt;Array.&lt;Object&gt;&gt;]</code>
Get the list of children pids of the given pid.

**Kind**: global function  
**Returns**: <code>Promise.&lt;Array.&lt;Object&gt;&gt;</code> - Only when the callback is not provided.  
**Access**: public  

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| pid | <code>Number</code> \| <code>String</code> |  | A pid. If -1 will return all the pids. |
| [options] | <code>Object</code> |  | Optional options object. |
| [options.root] | <code>Boolean</code> | <code>false</code> | Include the provided pid in the list. Ignored if -1 is passed as pid. |
| [callback] | <code>function</code> |  | Called when the list is ready. If not provided a promise is returned instead. |

## Related

- [pidusage][gh:pidusage] -
Cross-platform process cpu % and memory usage of a PID

## Authors

- **Simone Primarosa** - [simonepri][github:simonepri]

See also the list of [contributors][contributors] who participated in this project.

## License

This project is licensed under the MIT License - see the [license][license] file for details.

<!-- Links -->
[new issue]: https://github.com/simonepri/pidtree/issues/new
[license]: https://github.com/simonepri/pidtree/tree/master/license
[contributors]: https://github.com/simonepri/pidtree/contributors

[github:simonepri]: https://github.com/simonepri

[gh:esm]: https://nodejs.org/api/esm.html
[gh:pidusage]: https://github.com/soyuka/pidusage
[gh:ps-tree]: https://github.com/indexzero/ps-tree
[gh:ps-tree-um]: https://github.com/indexzero/ps-tree/issues/30

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