# pidusage > Cross-platform process cpu % and memory usage of a PID Latest version **4.0.1** (published 2025-04-26) · MIT license · 0 weekly downloads ## Install ```sh npm install pidusage pnpm add pidusage yarn add pidusage bun add pidusage ``` ## Health **Score 23/100 (F)** — status: maintenance-mode. Positive: has types package; no vulnerabilities; high quality score. Warnings: low downloads; no esm support. Negative: stale; low maintenance score; declining downloads. ## Facts | | | |---|---| | Version | 4.0.1 | | Published | 2025-04-26 | | First published | 2014-05-08 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | separate (@types/pidusage) | | Module format | CommonJS | | Node | >=18 | | Dependencies | 1 | | Unpacked size | 35.2 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 546 | | Author | soyuka | | Maintainers | tknew, soyuka, simonepri, vmarchaud | | Keywords | pid, usage, ps, cpu, memory, proc | ## Links - npm: https://www.npmjs.com/package/pidusage - Repository: https://github.com/soyuka/pidusage - Issues: https://github.com/soyuka/pidusage/issues - npm.io page: https://npm.io/package/pidusage ## Dependencies (1) - [safe-buffer](https://npm.io/package/safe-buffer.md) ^5.2.1 ## 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 - 4.0.1 (latest) — 2025-04-26 - 4.0.0 — 2025-02-09 - 3.0.2 — 2022-10-25 - 3.0.1 — 2022-10-13 - 3.0.0 — 2021-10-22 - 2.0.21 — 2020-07-17 - 2.0.20 — 2020-05-19 - 2.0.19 — 2020-05-14 - 2.0.18 — 2020-02-18 - 2.0.17 — 2018-09-12 - 2.0.16 — 2018-08-22 - 2.0.15 — 2018-07-24 - 2.0.12 — 2018-07-19 - 2.0.13 — 2018-07-13 - 2.0.11 — 2018-07-05 - … 37 more at https://npm.io/package/pidusage/versions ## README # pidusage [![Lint](https://github.com/soyuka/pidusage/workflows/lint/badge.svg?branch=main)](https://github.com/soyuka/pidusage/actions?query=workflow:lint+branch:main) [![MacOS](https://github.com/soyuka/pidusage/workflows/test-macos/badge.svg?branch=main)](https://github.com/soyuka/pidusage/actions?query=workflow:test-macos+branch:main) [![Ubuntu](https://github.com/soyuka/pidusage/workflows/linux/badge.svg?branch=main)](https://github.com/soyuka/pidusage/actions?query=workflow:linux+branch:main) [![Windows](https://github.com/soyuka/pidusage/workflows/test-windows/badge.svg?branch=main)](https://github.com/soyuka/pidusage/actions?query=workflow:test-windows+branch:main) [![Alpine](https://github.com/soyuka/pidusage/workflows/test-alpine/badge.svg?branch=main)](https://github.com/soyuka/pidusage/actions?query=workflow:test-alpine+branch:main) [![Code coverage](https://img.shields.io/codecov/c/github/soyuka/pidusage/master.svg)](https://codecov.io/gh/soyuka/pidusage) [![npm version](https://img.shields.io/npm/v/pidusage.svg)](https://www.npmjs.com/package/pidusage) [![license](https://img.shields.io/github/license/soyuka/pidusage.svg)](https://github.com/soyuka/pidusage/tree/master/license) Cross-platform process cpu % and memory usage of a PID. ## Synopsis Ideas from https://github.com/arunoda/node-usage but with no C-bindings. Please note that if you need to check a Node.JS script process cpu and memory usage, you can use [`process.cpuUsage`][node:cpuUsage] and [`process.memoryUsage`][node:memUsage] since node v6.1.0. This script remain useful when you have no control over the remote script, or if the process is not a Node.JS process. ## Usage ```js var pidusage = require('pidusage') pidusage(process.pid, function (err, stats) { console.log(stats) // => { // cpu: 10.0, // percentage (from 0 to 100*vcore) // memory: 357306368, // bytes // ppid: 312, // PPID // pid: 727, // PID // ctime: 867000, // ms user + system time // elapsed: 6650000, // ms since the start of the process // timestamp: 864000000 // ms since epoch // } cb() }) // It supports also multiple pids pidusage([727, 1234], function (err, stats) { console.log(stats) // => { // 727: { // cpu: 10.0, // percentage (from 0 to 100*vcore) // memory: 357306368, // bytes // ppid: 312, // PPID // pid: 727, // PID // ctime: 867000, // ms user + system time // elapsed: 6650000, // ms since the start of the process // timestamp: 864000000 // ms since epoch // }, // 1234: { // cpu: 0.1, // percentage (from 0 to 100*vcore) // memory: 3846144, // bytes // ppid: 727, // PPID // pid: 1234, // PID // ctime: 0, // ms user + system time // elapsed: 20000, // ms since the start of the process // timestamp: 864000000 // ms since epoch // } // } }) // If no callback is given it returns a promise instead const stats = await pidusage(process.pid) console.log(stats) // => { // cpu: 10.0, // percentage (from 0 to 100*vcore) // memory: 357306368, // bytes // ppid: 312, // PPID // pid: 727, // PID // ctime: 867000, // ms user + system time // elapsed: 6650000, // ms since the start of the process // timestamp: 864000000 // ms since epoch // } // Avoid using setInterval as they could overlap with asynchronous processing function compute(cb) { pidusage(process.pid, function (err, stats) { console.log(stats) // => { // cpu: 10.0, // percentage (from 0 to 100*vcore) // memory: 357306368, // bytes // ppid: 312, // PPID // pid: 727, // PID // ctime: 867000, // ms user + system time // elapsed: 6650000, // ms since the start of the process // timestamp: 864000000 // ms since epoch // } cb() }) } function interval(time) { setTimeout(function() { compute(function() { interval(time) }) }, time) } // Compute statistics every second: interval(1000) // Above example using async/await const compute = async () => { const stats = await pidusage(process.pid) // do something } // Compute statistics every second: const interval = async (time) => { setTimeout(async () => { await compute() interval(time) }, time) } interval(1000) ``` ## Compatibility | Property | Linux | FreeBSD | NetBSD | SunOS | macOS | Win | AIX | Alpine | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `cpu` | ✅ | ❓ | ❓ | ❓ | ✅ | ℹ️ | ❓ | ✅ | | `memory` | ✅ | ❓ | ❓ | ❓ | ✅ | ✅ | ❓ | ✅ | | `pid` | ✅ | ❓ | ❓ | ❓ | ✅ | ✅ | ❓ | ✅ | | `ctime` | ✅ | ❓ | ❓ | ❓ | ✅ | ✅ | ❓ | ✅ | | `elapsed` | ✅ | ❓ | ❓ | ❓ | ✅ | ✅ | ❓ | ✅ | | `timestamp` | ✅ | ❓ | ❓ | ❓ | ✅ | ✅ | ❓ | ✅ | ✅ = Working ℹ️ = Not Accurate ❓ = Should Work ❌ = Not Working Please if your platform is not supported or if you have reported wrong readings [file an issue][new issue]. By default, pidusage will use `procfile` parsing on most unix systems. If you want to use `ps` instead use the `usePs` option: ``` pidusage(pid, {usePs: true}) ``` ## API ### pidusage(pids, [options = {}], [callback]) ⇒ [Promise.<Object>] Get pid informations. **Kind**: global function **Returns**: Promise.<Object> - Only when the callback is not provided. **Access**: public | Param | Type | Description | | --- | --- | --- | | pids | Number \| Array.<Number> \| String \| Array.<String> | A pid or a list of pids. | | [options] | object | Options object. See the table below. | | [callback] | function | Called when the statistics are ready. If not provided a promise is returned instead. | ### options Setting the options programatically will override environment variables | Param | Type | Environment variable | Default | Description | | --- | --- | --- | --- | --- | | [usePs] | boolean | `PIDUSAGE_USE_PS`| `false` | When true uses `ps` instead of proc files to fetch process information | | [maxage] | number | `PIDUSAGE_MAXAGE`| `60000` | Max age of a process on history. | `PIDUSAGE_SILENT=1` can be used to remove every console message triggered by pidusage. ### pidusage.clear() If needed this function can be used to delete all in-memory metrics and clear the event loop. This is not necessary before exiting as the interval we're registring does not hold up the event loop. ## Related - [pidusage-tree][gh:pidusage-tree] - Compute a pidusage tree ## Authors - **Antoine Bluchet** - [soyuka][github:soyuka] - **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. [new issue]: https://github.com/soyuka/pidusage/issues/new [license]: https://github.com/soyuka/pidusage/tree/master/LICENSE [contributors]: https://github.com/soyuka/pidusage/contributors [github:soyuka]: https://github.com/soyuka [github:simonepri]: https://github.com/simonepri [gh:pidusage-tree]: https://github.com/soyuka/pidusage-tree [node:cpuUsage]: https://nodejs.org/api/process.html#process_process_cpuusage_previousvalue [node:memUsage]: https://nodejs.org/api/process.html#process_process_memoryusage --- _Source: https://npm.io/package/pidusage · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._