Node.js os Module

What Is the os Module?

os is a built-in module that exposes operating-system-level information: platform ('darwin', 'linux', 'win32'), CPU core details, total and free memory, network interfaces, and the current user's home directory, without needing any external package.

It's especially useful for health-check endpoints, deciding how many worker processes to spawn (matching CPU core count), and diagnostic logging that helps explain why an app behaves differently across environments.

import os from 'node:os';

console.log('Platform:', os.platform());
console.log('CPU cores:', os.cpus().length);
console.log('Total memory (GB):', (os.totalmem() / 1024 ** 3).toFixed(1));
console.log('Free memory (GB):', (os.freemem() / 1024 ** 3).toFixed(1));

os.totalmem()/os.freemem() return bytes, dividing by 1024 ** 3 converts them into a human-friendly gigabyte figure.

Common os Methods

os.platform()     // 'darwin', 'linux', 'win32'
os.cpus()          // array of CPU core details
os.totalmem()       // total system memory in bytes
os.freemem()        // free system memory in bytes
os.homedir()         // current user's home directory

• os.platform() identifies the operating system, useful for platform-specific logic.
• os.cpus() returns an array, one entry per logical CPU core, use .length for a simple core count.
• Memory methods (totalmem, freemem) return raw byte counts.
• os.homedir() and os.tmpdir() give safe, cross-platform locations for user files and temp files.

os Module Cheatsheet

System information you can read directly from Node.js.

Scaling Workers to CPU Count

One of the most practical uses of os.cpus() is deciding how many worker processes to spawn, whether via the cluster module or worker_threads. Since Node.js's main JavaScript thread is single-threaded, matching the worker count to the number of available CPU cores makes full use of the hardware.

import os from 'node:os';
import cluster from 'node:cluster';

const cpuCount = os.cpus().length;

if (cluster.isPrimary) {
  for (let i = 0; i < cpuCount; i++) {
    cluster.fork();
  }
}

This pattern is explored fully in the Node.js Clustering lesson later in this course.

Using os for Health Checks

Basic health-check or /status endpoints often report memory and CPU information so monitoring tools can flag machines running low on resources before they fail outright.

app.get('/status', (req, res) => {
  res.json({
    uptime: process.uptime(),
    freeMemoryMB: Math.round(os.freemem() / 1024 / 1024),
    loadAverage: os.loadavg(),
  });
});

Common Mistakes

• Assuming os.freemem() reflects memory available specifically to your Node.js process rather than the whole machine.
• Hardcoding worker counts instead of deriving them from os.cpus().length.
• Forgetting os.loadavg() returns [0, 0, 0] on Windows, since load averages are a Unix concept.
• Confusing os.platform() (the OS) with os.arch() (the CPU architecture).

Key Takeaways

• The os module reads operating-system-level details like platform, CPU, and memory.
• os.cpus().length is commonly used to size worker pools for clustering.
• Memory-related methods return raw bytes, convert as needed for display.
• os.homedir()/os.tmpdir() provide safe, cross-platform file locations.