OS Utils

0.0.14 · abandoned · verified Sun Apr 19

The `os-utils` package is a Node.js library offering fundamental operating system utility functions. It enables developers to retrieve basic system metrics such as CPU usage (calculated per second, not as an average), total and free memory, platform identification, and system/process uptime. The package's latest version, 0.0.14, was released on October 30, 2012, signifying that its development has ceased and it is no longer actively maintained. Its release cadence was effectively non-existent after this initial publication. Compared to contemporary system monitoring libraries like `node-os-utils` or `systeminformation`, `os-utils` provides a very limited, callback-based API, lacks modern features such as TypeScript support, sophisticated error handling, or intelligent caching mechanisms, making it unsuitable for modern Node.js applications or environments requiring robust system insights.

Common errors

```
ERR_REQUIRE_ESM: require() of ES Module ... not supported. Instead change the require of ... to a dynamic import()
```
cause Attempting to use `require('os-utils')` within an ECMAScript Module (ESM) file or project configured as 'type': 'module' in `package.json`.

fix Ensure your file is a CommonJS module (e.g., ends with `.cjs` or `package.json` specifies `'type': 'commonjs'`) or refactor your project to use an ESM-compatible system monitoring library. You *cannot* `import` this package directly as it's pure CommonJS.
```
TypeError: os.cpuUsage is not a function
```
cause Incorrectly trying to destructure the module or using an import syntax that results in `os` not being the module object, or the `os-utils` package wasn't installed correctly.

fix Always import `os-utils` using `const os = require('os-utils');` and access its methods as `os.methodName()`. Verify `npm install os-utils` completed successfully.

Warnings

breaking The `os-utils` package is completely unmaintained, with its last update over a decade ago (version 0.0.14 published in October 2012). It is highly likely to have compatibility issues with modern Node.js versions and environments.
Fix: Migrate to actively maintained alternatives like `node-os-utils` (https://www.npmjs.com/package/node-os-utils) or `systeminformation` (https://www.npmjs.com/package/systeminformation) for reliable system monitoring.
gotcha The package uses a callback-based API, which is an outdated pattern in modern asynchronous JavaScript. Integrating it into Promise-based or async/await codebases requires manual promisification or wrapper functions.
Fix: Consider wrapping `os-utils` functions in Promises for better integration, or, preferably, switch to a modern library that provides native Promise support.
gotcha The `cpuUsage` and `cpuFree` functions calculate CPU usage for 'the next second' and are not true averages like those provided by Node.js's native `os` module or other monitoring tools. This can lead to misleading or inconsistent metrics.
Fix: Be aware of this distinction when interpreting CPU metrics. For more accurate average CPU usage, consider using the native `os.cpus()` module with custom calculation logic or a more robust monitoring library.
breaking Being an unmaintained package, `os-utils` may contain unpatched security vulnerabilities. Directly interacting with operating system APIs through outdated code poses a significant supply chain risk.
Fix: Avoid using `os-utils` in production environments. Prioritize secure, actively maintained packages for any OS-level interactions to mitigate potential security risks.

Install

npm install os-utils npm
yarn add os-utils yarn
pnpm add os-utils pnpm

Imports

module object
wrong:
```
import os from 'os-utils';
```
correct:
```
const os = require('os-utils');
```
This package is a CommonJS module from 2012. ESM `import` syntax will result in an `ERR_REQUIRE_ESM` error in most modern Node.js environments unless specific compatibility flags or bundler configurations are used. Always use `require()`.
cpuUsage
wrong:
```
import { cpuUsage } from 'os-utils';
```
correct:
```
const os = require('os-utils');
os.cpuUsage(function(v) { /* ... */ });
```
Functions like `cpuUsage` are properties of the default exported module object. They are accessed via `os.cpuUsage()`, not as named exports.
freememPercentage
wrong:
```
import { freememPercentage } from 'os-utils';
```
correct:
```
const os = require('os-utils');
os.freememPercentage();
```
Similar to `cpuUsage`, this is a method on the default module object. Attempts to destructure or directly import it will fail.

Quickstart

This quickstart demonstrates how to initialize `os-utils` and retrieve various system metrics such as CPU usage, memory information, and system details using its callback-based API.

const os = require('os-utils');

// Get CPU usage for the next second
os.cpuUsage(function(v) {
  console.log('CPU Usage (%): ' + v);
});

// Get free CPU for the next second
os.cpuFree(function(v) {
  console.log('CPU Free (%): ' + v);
});

// Get platform name
console.log('Platform:', os.platform());

// Get number of CPUs
console.log('CPU Count:', os.cpuCount());

// Get current free memory in MB
console.log('Free Memory (MB):', os.freemem());

// Get total memory in MB
console.log('Total Memory (MB):', os.totalmem());

// Get free memory percentage
console.log('Free Memory Percentage (%):', os.freememPercentage());

view raw JSON →