Node module for macOS system statistics. Get real-time CPU, GPU, battery, memory, disk, and sensor data from your Mac.
npm i macstats -g# Show system stats (single snapshot)
macstats
# Show all disks including system volumes
macstats --detailed
macstats -d
# Launch real-time dashboard with live updates
macstats --watch
macstats -w
# Launch real-time dashboard with all disks
macstats -w -d
# Show help
macstats --helpqorCtrl+C- Exitr- Force refresh
import {
getCpuData,
getGpuData,
getBatteryData,
getRAMUsage,
getDiskInfo,
getFanData,
getPowerData,
getSensorData,
getSystemData
} from 'macstats';
// Or use synchronous versions
import {
getCpuDataSync,
getGpuDataSync,
getBatteryDataSync,
getRAMUsageSync,
getDiskInfoSync,
getFanDataSync,
getPowerDataSync,
getSensorDataSync,
getSystemDataSync
} from 'macstats';Get CPU temperature, die temperature, and voltage.
Returns: Promise<CPU> / CPU
| Property | Type | Description |
|---|---|---|
temperature |
number |
CPU temperature in °C |
temperatureDie |
number |
CPU die temperature in °C |
voltage |
number |
CPU voltage in Volts |
Example:
const cpu = await getCpuData();
console.log(`CPU Temp: ${cpu.temperature}°C`);
console.log(`CPU Die Temp: ${cpu.temperatureDie}°C`);Get CPU usage statistics including load averages.
Returns: Promise<CPUUsage> / CPUUsage
| Property | Type | Description |
|---|---|---|
userLoad |
number |
User CPU load (0.0 - 1.0) |
systemLoad |
number |
System CPU load (0.0 - 1.0) |
idleLoad |
number |
Idle CPU load (0.0 - 1.0) |
totalUsage |
number |
Total CPU usage (0.0 - 1.0) |
totalUsagePercent |
number |
Total CPU usage as percentage (0 - 100) |
loadAvg1 |
number |
1 minute load average |
loadAvg5 |
number |
5 minute load average |
loadAvg15 |
number |
15 minute load average |
Example:
const usage = await getCPUUsage();
console.log(`CPU Usage: ${usage.totalUsagePercent}%`);
console.log(`Load Average (1m): ${usage.loadAvg1}`);Get GPU temperature, voltage, and usage.
Returns: Promise<GPU> / GPU
| Property | Type | Description |
|---|---|---|
temperature |
number |
GPU temperature in °C |
voltage |
number |
GPU voltage in Volts |
usage |
number |
GPU usage percentage (0-100) |
Example:
const gpu = await getGpuData();
console.log(`GPU Temp: ${gpu.temperature}°C`);
console.log(`GPU Usage: ${gpu.usage}%`);Get comprehensive battery information including charge, health, and time remaining.
Returns: Promise<Battery> / Battery
| Property | Type | Description |
|---|---|---|
external_connected |
boolean |
Is external power connected |
battery_installed |
boolean |
Is battery installed |
is_charging |
boolean |
Is battery currently charging |
fully_charged |
boolean |
Is battery fully charged |
voltage |
number |
Battery voltage in mV |
cycle_count |
number |
Number of charge cycles |
design_capacity |
number |
Design capacity in mAh |
max_capacity |
number |
Maximum capacity in mAh |
current_capacity |
number |
Current capacity in mAh |
design_cycle_count |
number |
Design cycle count |
time_remaining |
number |
Time remaining in seconds |
time_remaining_formatted |
string |
Formatted time remaining (e.g., "6:30:45") |
temperature |
number |
Battery temperature in °C |
percentage |
number |
Battery health percentage (0-100) |
cycle_percentage |
number |
Cycle count percentage (0-100) |
amperage |
number |
Current amperage in mA |
power |
number |
Power in Watts |
charge_percent |
number |
Current charge percentage (0-100) |
health_percent |
number |
Battery health percentage (0-100) |
Example:
const battery = await getBatteryData();
console.log(`Charge: ${battery.charge_percent}%`);
console.log(`Health: ${battery.health_percent}%`);
console.log(`Time Remaining: ${battery.time_remaining_formatted}`);
console.log(`Cycles: ${battery.cycle_count}/${battery.design_cycle_count}`);Get memory voltage information.
Returns: Promise<Memory> / Memory
| Property | Type | Description |
|---|---|---|
voltage |
number |
Memory voltage in Volts |
Get detailed RAM usage statistics.
Returns: Promise<RAMUsage> / RAMUsage
| Property | Type | Description |
|---|---|---|
total |
number |
Total RAM in bytes |
totalGB |
number |
Total RAM in GB |
used |
number |
Used RAM in bytes |
usedGB |
number |
Used RAM in GB |
free |
number |
Free RAM in bytes |
freeGB |
number |
Free RAM in GB |
usagePercent |
number |
Usage percentage (0-100) |
active |
number |
Active RAM in bytes |
activeGB |
number |
Active RAM in GB |
inactive |
number |
Inactive RAM in bytes |
inactiveGB |
number |
Inactive RAM in GB |
wired |
number |
Wired RAM in bytes |
wiredGB |
number |
Wired RAM in GB |
compressed |
number |
Compressed RAM in bytes |
compressedGB |
number |
Compressed RAM in GB |
app |
number |
App memory in bytes |
appGB |
number |
App memory in GB |
cache |
number |
Cache memory in bytes |
cacheGB |
number |
Cache memory in GB |
swapTotal |
number |
Total swap in bytes |
swapTotalGB |
number |
Total swap in GB |
swapUsed |
number |
Used swap in bytes |
swapUsedGB |
number |
Used swap in GB |
swapFree |
number |
Free swap in bytes |
swapFreeGB |
number |
Free swap in GB |
pressureLevel |
number |
Memory pressure level (1=normal, 2=warning, 4=critical) |
pressureStatus |
string |
Memory pressure status ("Normal", "Warning", or "Critical") |
Example:
const ram = await getRAMUsage();
console.log(`RAM Usage: ${ram.usedGB}GB / ${ram.totalGB}GB (${ram.usagePercent}%)`);
console.log(`Memory Pressure: ${ram.pressureStatus}`);
console.log(`Swap: ${ram.swapUsedGB}GB / ${ram.swapTotalGB}GB`);Get information about all mounted disks.
Returns: Promise<DiskInfo[]> / DiskInfo[]
| Property | Type | Description |
|---|---|---|
name |
string |
Disk name |
mountPoint |
string |
Mount point path |
fileSystem |
string |
File system type |
totalSize |
number |
Total size in bytes |
totalSizeGB |
number |
Total size in GB |
freeSize |
number |
Free size in bytes |
freeSizeGB |
number |
Free size in GB |
usedSize |
number |
Used size in bytes |
usedSizeGB |
number |
Used size in GB |
usagePercent |
number |
Usage percentage (0-100) |
bsdName |
string |
BSD name (e.g., "disk0s1") |
isRemovable |
boolean |
Is removable media |
Example:
const disks = await getDiskInfo();
disks.forEach(disk => {
console.log(`${disk.name}: ${disk.usedSizeGB}GB / ${disk.totalSizeGB}GB (${disk.usagePercent}%)`);
});Get fan speed information for all fans.
Returns: Promise<Fan> / Fan
The Fan object is a dictionary where keys are fan indices and values are FanInfo objects:
| Property | Type | Description |
|---|---|---|
rpm |
number |
Current fan speed in RPM |
min |
number |
Minimum fan speed in RPM |
max |
number |
Maximum fan speed in RPM |
Example:
const fans = await getFanData();
Object.entries(fans).forEach(([index, fan]) => {
console.log(`Fan ${index}: ${fan.rpm} RPM (${fan.min}-${fan.max})`);
});Get comprehensive power consumption metrics for all system components.
Returns: Promise<Power> / Power
| Property | Type | Description |
|---|---|---|
cpu |
number |
CPU power consumption in Watts |
gpu |
number |
GPU power consumption in Watts |
ane |
number |
ANE (Apple Neural Engine) power in Watts |
all |
number |
Combined power (cpu + gpu + ane) in Watts |
system |
number |
Total system power consumption in Watts |
ram |
number |
RAM power consumption in Watts |
gpu_ram |
number |
GPU RAM (SRAM) power consumption in Watts |
Example:
const power = await getPowerData();
console.log(`CPU Power: ${power.cpu}W`);
console.log(`GPU Power: ${power.gpu}W`);
console.log(`ANE Power: ${power.ane}W`);
console.log(`RAM Power: ${power.ram}W`);
console.log(`Combined (CPU+GPU+ANE): ${power.all}W`);
console.log(`Total System Power: ${power.system}W`);Get all available sensor readings including temperatures, voltages, and currents.
Returns: Promise<SensorData> / SensorData
| Property | Type | Description |
|---|---|---|
temperatures |
Sensor[] |
Array of temperature sensors |
voltages |
Sensor[] |
Array of voltage sensors |
currents |
Sensor[] |
Array of current sensors |
Sensor Object:
| Property | Type | Description |
|---|---|---|
name |
string |
Sensor name/identifier |
value |
number |
Sensor reading value |
Example:
const sensors = await getSensorData();
sensors.temperatures.forEach(sensor => {
console.log(`${sensor.name}: ${sensor.value}°C`);
});Get system information including OS version, model, and hardware details.
Returns: Promise<SystemInfo> / SystemInfo
| Property | Type | Description |
|---|---|---|
totalMemory |
number |
Total RAM in bytes |
totalMemoryGB |
number |
Total RAM in GB |
uptime |
number |
System uptime in seconds |
uptimeFormatted |
string |
Formatted uptime (e.g., "5d 3h 42m") |
osVersion |
string |
macOS version (e.g., "14.1") |
osCodename |
string |
macOS codename (e.g., "Sonoma") |
modelName |
string |
Model name (e.g., "Apple M3 Pro") |
hardwareModel |
string |
Hardware model (e.g., "Mac14,6") |
serialNumber |
string |
Serial number |
screenSize |
string |
Screen size (e.g., "14-inch") |
releaseYear |
string |
Release year and month (e.g., "Nov 2023") |
Example:
const system = await getSystemData();
console.log(`Model: ${system.modelName}`);
console.log(`OS: macOS ${system.osVersion} (${system.osCodename})`);
console.log(`Uptime: ${system.uptimeFormatted}`);
console.log(`RAM: ${system.totalMemoryGB}GB`);import {
getCpuData,
getGpuData,
getBatteryData,
getRAMUsage,
getDiskInfo,
getFanData,
getPowerData,
getSensorData,
getSystemData
} from 'macstats';
async function main() {
try {
const [system, cpu, gpu, battery, ram, disks, fans, power, sensors] = await Promise.all([
getSystemData(),
getCpuData(),
getGpuData(),
getBatteryData(),
getRAMUsage(),
getDiskInfo(),
getFanData(),
getPowerData(),
getSensorData()
]);
console.log('=== System ===');
console.log(`Model: ${system.modelName}`);
console.log(`OS: macOS ${system.osVersion}`);
console.log(`Uptime: ${system.uptimeFormatted}`);
console.log('\n=== CPU ===');
console.log(`Temperature: ${cpu.temperature}°C`);
console.log(`Die Temperature: ${cpu.temperatureDie}°C`);
console.log('\n=== GPU ===');
console.log(`Temperature: ${gpu.temperature}°C`);
console.log(`Usage: ${gpu.usage}%`);
console.log('\n=== Power ===');
console.log(`CPU: ${power.cpu}W`);
console.log(`GPU: ${power.gpu}W`);
console.log(`ANE: ${power.ane}W`);
console.log(`RAM: ${power.ram}W`);
console.log(`Combined: ${power.all}W`);
console.log(`System Total: ${power.system}W`);
console.log('\n=== Memory ===');
console.log(`Usage: ${ram.usedGB}GB / ${ram.totalGB}GB (${ram.usagePercent}%)`);
console.log('\n=== Battery ===');
console.log(`Charge: ${battery.charge_percent}%`);
console.log(`Health: ${battery.health_percent}%`);
console.log('\n=== Disks ===');
disks.forEach(disk => {
console.log(`${disk.name}: ${disk.usedSizeGB}GB / ${disk.totalSizeGB}GB`);
});
console.log('\n=== Fans ===');
Object.entries(fans).forEach(([index, fan]) => {
console.log(`Fan ${index}: ${fan.rpm} RPM`);
});
} catch (error) {
console.error('Error:', error);
}
}
main();All functions have both async and sync versions:
- Async:
getCpuData(),getGpuData(), etc. - ReturnsPromise - Sync:
getCpuDataSync(),getGpuDataSync(), etc. - Returns value directly
Use synchronous versions for simple scripts, async versions for better performance in applications.
- macOS 10.12 or later
- Node.js 18.0 or later
MIT