Node.js os Module Guide

The os module provides operating system utilities for accessing system information, CPU data, memory stats, and more. Here's how to use it.

Basic System Info#

import os from 'node:os';

// Platform and architecture
console.log('Platform:', os.platform());    // 'darwin', 'linux', 'win32'
console.log('Architecture:', os.arch());    // 'x64', 'arm64'
console.log('OS Type:', os.type());         // 'Darwin', 'Linux', 'Windows_NT'
console.log('Release:', os.release());      // '21.6.0'
console.log('Version:', os.version());      // 'Darwin Kernel Version 21.6.0'

// Machine info
console.log('Hostname:', os.hostname());
console.log('Home Dir:', os.homedir());
console.log('Temp Dir:', os.tmpdir());

CPU Information#

import os from 'node:os';

// CPU cores
const cpus = os.cpus();
console.log('CPU Cores:', cpus.length);
console.log('CPU Model:', cpus[0].model);
console.log('CPU Speed:', cpus[0].speed, 'MHz');

// Detailed CPU info
cpus.forEach((cpu, index) => {
  console.log(`Core ${index}:`, {
    model: cpu.model,
    speed: cpu.speed,
    times: cpu.times,
  });
});

// CPU usage calculation
function getCPUUsage() {
  const cpus = os.cpus();

  return cpus.map((cpu) => {
    const total = Object.values(cpu.times).reduce((a, b) => a + b, 0);
    const idle = cpu.times.idle;
    return {
      usage: ((total - idle) / total * 100).toFixed(2) + '%',
      idle: (idle / total * 100).toFixed(2) + '%',
    };
  });
}

Memory Information#

import os from 'node:os';

// Memory in bytes
const totalMem = os.totalmem();
const freeMem = os.freemem();

console.log('Total Memory:', formatBytes(totalMem));
console.log('Free Memory:', formatBytes(freeMem));
console.log('Used Memory:', formatBytes(totalMem - freeMem));
console.log('Memory Usage:', ((1 - freeMem / totalMem) * 100).toFixed(2) + '%');

function formatBytes(bytes) {
  const units = ['B', 'KB', 'MB', 'GB', 'TB'];
  let unitIndex = 0;

  while (bytes >= 1024 && unitIndex < units.length - 1) {
    bytes /= 1024;
    unitIndex++;
  }

  return `${bytes.toFixed(2)} ${units[unitIndex]}`;
}

Network Interfaces#

import os from 'node:os';

const interfaces = os.networkInterfaces();

// List all interfaces
for (const [name, addresses] of Object.entries(interfaces)) {
  console.log(`\n${name}:`);
  addresses.forEach((addr) => {
    console.log(`  ${addr.family}: ${addr.address}`);
    console.log(`    MAC: ${addr.mac}`);
    console.log(`    Internal: ${addr.internal}`);
  });
}

// Get local IP address
function getLocalIP() {
  const interfaces = os.networkInterfaces();

  for (const addresses of Object.values(interfaces)) {
    for (const addr of addresses) {
      if (addr.family === 'IPv4' && !addr.internal) {
        return addr.address;
      }
    }
  }

  return '127.0.0.1';
}

console.log('Local IP:', getLocalIP());

User Information#

import os from 'node:os';

// Current user info
const userInfo = os.userInfo();
console.log('Username:', userInfo.username);
console.log('Home Dir:', userInfo.homedir);
console.log('Shell:', userInfo.shell);
console.log('UID:', userInfo.uid);
console.log('GID:', userInfo.gid);

// With encoding option
const userInfoBuffer = os.userInfo({ encoding: 'buffer' });
console.log('Username (buffer):', userInfoBuffer.username.toString());

System Uptime and Load#

import os from 'node:os';

// System uptime
const uptime = os.uptime();
console.log('Uptime:', formatUptime(uptime));

function formatUptime(seconds) {
  const days = Math.floor(seconds / 86400);
  const hours = Math.floor((seconds % 86400) / 3600);
  const minutes = Math.floor((seconds % 3600) / 60);
  const secs = Math.floor(seconds % 60);

  return `${days}d ${hours}h ${minutes}m ${secs}s`;
}

// Load average (Unix only)
const loadAvg = os.loadavg();
console.log('Load Average (1, 5, 15 min):', loadAvg);

// Load as percentage of CPUs
const cpuCount = os.cpus().length;
console.log('Load % (1 min):', (loadAvg[0] / cpuCount * 100).toFixed(2) + '%');

Constants#

import os from 'node:os';

// Signal constants
console.log('SIGINT:', os.constants.signals.SIGINT);
console.log('SIGTERM:', os.constants.signals.SIGTERM);
console.log('SIGKILL:', os.constants.signals.SIGKILL);

// Error constants
console.log('ENOENT:', os.constants.errno.ENOENT);
console.log('EACCES:', os.constants.errno.EACCES);
console.log('EPERM:', os.constants.errno.EPERM);

// Priority constants
console.log('Priority Low:', os.constants.priority.PRIORITY_LOW);
console.log('Priority Normal:', os.constants.priority.PRIORITY_NORMAL);
console.log('Priority High:', os.constants.priority.PRIORITY_HIGH);

Process Priority#

import os from 'node:os';

// Get current process priority
const priority = os.getPriority();
console.log('Current Priority:', priority);

// Set process priority (requires appropriate permissions)
try {
  os.setPriority(os.constants.priority.PRIORITY_LOW);
  console.log('Priority set to low');
} catch (err) {
  console.error('Could not set priority:', err.message);
}

// Set priority for specific PID
try {
  os.setPriority(process.pid, os.constants.priority.PRIORITY_NORMAL);
} catch (err) {
  console.error('Error:', err.message);
}

System Monitor#

import os from 'node:os';

class SystemMonitor {
  constructor(interval = 5000) {
    this.interval = interval;
    this.history = [];
  }

  getStats() {
    const cpus = os.cpus();
    const totalMem = os.totalmem();
    const freeMem = os.freemem();

    return {
      timestamp: new Date(),
      cpu: {
        cores: cpus.length,
        model: cpus[0].model,
        loadAvg: os.loadavg(),
      },
      memory: {
        total: totalMem,
        free: freeMem,
        used: totalMem - freeMem,
        usagePercent: ((1 - freeMem / totalMem) * 100).toFixed(2),
      },
      uptime: os.uptime(),
      platform: os.platform(),
      hostname: os.hostname(),
    };
  }

  start(callback) {
    this.timer = setInterval(() => {
      const stats = this.getStats();
      this.history.push(stats);

      // Keep last 100 entries
      if (this.history.length > 100) {
        this.history.shift();
      }

      callback(stats);
    }, this.interval);
  }

  stop() {
    if (this.timer) {
      clearInterval(this.timer);
    }
  }

  getHistory() {
    return this.history;
  }
}

// Usage
const monitor = new SystemMonitor(2000);

monitor.start((stats) => {
  console.clear();
  console.log('=== System Stats ===');
  console.log(`Memory: ${stats.memory.usagePercent}% used`);
  console.log(`Load Avg: ${stats.cpu.loadAvg.map(l => l.toFixed(2)).join(', ')}`);
  console.log(`Uptime: ${Math.floor(stats.uptime / 3600)} hours`);
});

// Stop after 30 seconds
setTimeout(() => monitor.stop(), 30000);

Cross-Platform Paths#

import os from 'node:os';
import path from 'node:path';

// Platform-specific paths
const homeDir = os.homedir();
const tempDir = os.tmpdir();

// Common directories
const appDataDir = process.env.APPDATA ||
  (os.platform() === 'darwin'
    ? path.join(homeDir, 'Library', 'Application Support')
    : path.join(homeDir, '.config'));

const cacheDir = process.env.XDG_CACHE_HOME ||
  (os.platform() === 'darwin'
    ? path.join(homeDir, 'Library', 'Caches')
    : path.join(homeDir, '.cache'));

console.log('App Data:', appDataDir);
console.log('Cache:', cacheDir);
console.log('Temp:', tempDir);

// EOL constant
console.log('Line ending:', JSON.stringify(os.EOL));
// '\n' on Unix, '\r\n' on Windows

Best Practices#

Usage:
✓ Cache static values
✓ Handle platform differences
✓ Use constants for signals/errors
✓ Format bytes for display

Performance:
✓ Avoid polling too frequently
✓ cpus() can be expensive
✓ Cache network interfaces
✓ Use async alternatives when available

Cross-Platform:
✓ Check platform for platform-specific code
✓ Use path.join for file paths
✓ Handle missing features gracefully
✓ Use os.EOL for line endings

Avoid:
✗ Assuming Unix-only features
✗ Ignoring permission errors
✗ Blocking with frequent calls
✗ Hardcoding platform values

The os module provides essential system information for Node.js applications. Use it for monitoring resources, configuring platform-specific behavior, and accessing user information. Remember that some features like load average are Unix-specific, and always handle cross-platform differences gracefully. For performance monitoring, cache static values and avoid polling too frequently.