systeminformation

System and OS information library for node.js
Explore Systeminformation docs »

Report bug · Request feature · Changelog

2019-03-12 - 5th birthday of systeminformation. This is amazing. Started as a small projekt just for myself, it now has > 8,000 lines of code, > 200 versions published, up to 100,000 downloads per month, > 1 Mio downloads overall. Thank you to all who contributed to this project!

New Version 4.0

This next major version release 4.0 comes with several optimizations and changes:

• new systeminformation website with better documentation and examples systeminformation.io
• added typescript definitions
• reworked network section: this will now return more information and allows to get networkStats for more than one interface at once.
• dockerContainerStats for multiple containers or all containers at once
• optimized graphics controller and display detection
• added wifiNetworks to get available wifi networks
• added vboxInfo to get detailed vm information
• added chassis information
• better Raspberry-PI detection
• lot of minor improvements

Breaking Changes: you will see some minor breaking changes. Read the detailed changelog.

Quick Start

Lightweight collection of 40+ functions to retrieve detailed hardware, system and OS information.

• simple to use
• get detailed information about system, cpu, baseboard, battery, memory, disks/filesystem, network, docker, software, services and processes
• supports Linux, macOS, partial Windows, FreeBSD, OpenBSD, NetBSD and SunOS support
• no npm dependencies (for production)

Installation

$ npm install systeminformation --save

Usage

All functions (except version and time) are implemented as asynchronous functions. Here a small example how to use them:

const si = require('systeminformation');

// promises style - new since version 3
si.cpu()
    .then(data => console.log(data))
    .catch(error => console.error(error));

Callback, Promises, Awync Await

News and Changes

Latest Activity

(last 7 major and minor version releases)

• Version 4.14.0: processes() added process path and params
• Version 4.13.0: networkConnections() added PID, process
• Version 4.12.0: networkInterfaces() added property virtual
• Version 4.11.0: wifiNetworks() added available wifi networks
• Version 4.10.0: graphics() added windows multiple display support, added display size, connection, ...
• Version 4.9.0: graphics() added vendor, refresh rate, current resolution
• Version 4.8.0: added vboxInfo() detailed virtual box info
• ...

You can find all changes here: detailed changelog

Core concept

Node.js comes with some basic OS information, but I always wanted a little more. So I came up to write this little library. This library is still work in progress. It is supposed to be used as a backend/server-side library (will definilely not work within a browser). It requires node.js version 4.0 and above.

I was able to test it on several Debian, Raspbian, Ubuntu distributions as well as macOS (Mavericks, Yosemite, El Captain, Sierra, High Sierra, Mojave) and some Windows 7, Windows 10, FreeBSD, OpenBSD, NetBSD and SunOS machines. Not all functions are supported on all operating systems. Have a look at the function reference in the docs to get further details.

If you have comments, suggestions & reports, please feel free to contact me!

I also created a nice little command line tool called mmon (micro-monitor) for Linux and macOS, also available via github and npm

Reference

Function Reference and OS Support

1. General

2. System (HW)

3. CPU

4. Memory

5. Battery

• See known issues if you have problem with macOS temperature or windows temperature

6. Graphics

7. Operating System

8. Current Load, Processes & Services

9. File System

10. Network related functions

11. Wifi networks

12. Docker

13. Virtual Box

14. "Get All at once" - functions

cb: Asynchronous Function Calls (callback)

Remember: all functions (except version and time) are implemented as asynchronous functions! There are now three ways to consume them:

Callback Style

const si = require('systeminformation');

si.cpu(function(data) {
    console.log('CPU Information:');
    console.log('- manufucturer: ' + data.manufacturer);
    console.log('- brand: ' + data.brand);
    console.log('- speed: ' + data.speed);
    console.log('- cores: ' + data.cores);
    console.log('- physical cores: ' + data.physicalCores);
    console.log('...');
})

Promises

Promises Style is new in version 3.0.

When omitting callback parameter (cb), then you can use all function in a promise oriented way. All functions (exept of version and time) are returning a promise, that you can consume:

const si = require('systeminformation');

si.cpu()
    .then(data => {
        console.log('CPU Information:');
        console.log('- manufucturer: ' + data.manufacturer);
        console.log('- brand: ' + data.brand);
        console.log('- speed: ' + data.speed);
        console.log('- cores: ' + data.cores);
        console.log('- physical cores: ' + data.physicalCores);
        console.log('...');
    })
    .catch(error => console.error(error));

Async / Await

Using async / await (available since node v7.6)

Since node v7.6 you can also use the async / await pattern. The above example would then look like this:

const si = require('systeminformation');

async function cpuData() {
    try {
        const data = await si.cpu();
        console.log('CPU Information:');
        console.log('- manufucturer: ' + data.manufacturer);
        console.log('- brand: ' + data.brand);
        console.log('- speed: ' + data.speed);
        console.log('- cores: ' + data.cores);
        console.log('- physical cores: ' + data.physicalCores);
        console.log('...');
    } catch (e) {
        console.log(e)
    }
}

Known Issues

macOS - Temperature Sensor

To be able to measure temperature on macOS I created a little additional package. Due to some difficulties in NPM with optionalDependencies I unfortunately was getting unexpected warnings on other platforms. So I decided to drop this optional dependency for macOS - so by default, you will not get correct values.

But if you need to detect macOS temperature just run the following additional installation command:

$ npm install osx-temperature-sensor --save

systeminformation will then detect this additional library and return the temperature when calling systeminformations standard function cpuTemperature()

Windows Temperature, Battery, ...

wmic - which is used to determine temperature and battery sometimes needs to be run with admin privileges. So if you do not get any values, try to run it again with according privileges. If you still do not get any values, your system might not support this feature. In some cases we also discovered that wmic returned incorrect temperature values.

Linux Temperature

In some cases you need to install the linux sensors package to be able to measure temperature e.g. on DEBIAN based systems by running sudo apt-get install lm-sensors

Linux S.M.A.R.T. Status

To be able to detect S.M.A.R.T. status on Linux you need to install smartmontools. On DEBIAN based linux distributions you can install it by running sudo apt-get install smartmontools

*: Additional Notes

In fsStats(), disksIO() and networkStats() the results / sec. values (rx_sec, IOPS, ...) are calculated correctly beginning with the second call of the function. It is determined by calculating the difference of transferred bytes / IOs divided by the time between two calls of the function.

The first time you are calling one of this functions, you will get -1 for transfer rates. The second time, you should then get statistics based on the time between the two calls ...

So basically, if you e.g. need a values for network stats every second, your code should look like this:

const si = require('systeminformation');

setInterval(function() {
    si.networkStats().then(data => {
        console.log(data);
    })
}, 1000)

Beginning with the second call, you get network transfer values per second.

Finding new issues

I am happy to discuss any comments and suggestions. Please feel free to contact me if you see any possibility of improvement!

Comments

If you have ideas or comments, please do not hesitate to contact me.

Happy monitoring!

Sincerely,

Sebastian Hildebrandt, +innovations

Credits

Written by Sebastian Hildebrandt sebhildebrandt

Contributers

• Guillaume Legrain glegrain
• Riccardo Novaglia richy24
• Quentin Busuttil Buzut
• lapsio lapsio
• csy csy
• Tiago Roldão tiagoroldao
• dragonjet dragonjet
• Adam Reis adamreisnz
• Jimi M ItsJimi
• Git² GitSquared
• weiyin weiyin
• Jorai Rijsdijk Erackron
• Rasmus Porsager porsager
• Nathan Patten nrpatten

OSX Temperature: credits here are going to:

• Massimiliano Marcon mmarcon for his work on smc-code
• Sébastien Lavoie lavoiesl for his work on osx-cpu-temp code.

Copyright Information

Linux is a registered trademark of Linus Torvalds. Apple, macOS, OS X are registered trademarks of Apple Inc., Windows is a registered trademark of Microsoft Corporation. Node.js is a trademark of Joyent Inc., Intel is a trademark of Intel Corporation, AMD is a trademark of Advanced Micro Devices Inc., Raspberry Pi is a trademark of the Raspberry Pi Foundation, Debian is a trademark of the Debian Project, Ubuntu is a trademark of Canonical Ltd., FreeBSD is a registered trademark of The FreeBSD Foundation, NetBSD is a registered trademark of The NetBSD Foundation, Docker is a trademark of Docker, Inc., Sun, Solaris, OpenSolaris and registered trademarks of Sun Microsystems.

All other trademarks are the property of their respective owners.

License

The MIT License (MIT)

Copyright © 2014-2019 Sebastian Hildebrandt, +innovations.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Further details see LICENSE file.

Changelog

Major Changes - Version 4

New Functions

• chassis(): chassis information

Breaking Changes

• networkStats(): will provide an array of stats for all given interfaces. In previous versions only one interface was provided as a parameter. Pass '*' for all interfaces
• networkStats(): rx and tx changed to rx_bytes and tx_bytes
• dockerContainerStats(): will provide an array of stats for all given docker containers. In previous versions only one interface was provided as a parameter. Pass '*' for all docker containers

Other Changes

• system() optimized system detection (e.g. new Raspberry Pi models, ...)
• system(), bios(), baseboard() information also as non-root (linux)
• graphics() better controller and display detection, fixes
• versions() optimization, fixes
• networkInterfaces() added operstate, type, duplex, mtu, speed, carrierChanges
• networkStats() added stats for errors, dropped
• added TypeScript definitions

Be aware, that the new version 4.x is NOT fully backward compatible to version 3.x ...

For major (breaking) changes - version 3 and 2 see end of page.

Version history

Major (breaking) Changes - Version 3

• works only with node.js v4.0.0 and above (using now internal ES6 promise function, arrow functions, ...)
• Promises. As you can see in the documentation, you can now also use it in a promise oriented way. But callbacks are still supported.
• Async/Await. Due to the promises support, systeminformation also works perfectly with the async/await pattern (available in node.js v7.6.0 and above). See example in the docs.
• cpuCurrentspeed: now returns an object with current minimal, maximal and average CPU frequencies of all cores.
• mem: now supports also newer versions of free (Version 3.3.10 and above); extended information avaliable (potentially available memory)
• fsStats: added information sum bytes read + write (tx) and sum transfer rate/sec (tx_sec)
• networkInterfaces: now providing one more detail: internal - true if this is an internal interface like "lo"
• networkConnections: instead of only counting sockets, you now get an array of objects with connection details for each socket (protocol, local and peer address, state)
• users: now provides an array of objects with users online including detailed session information (login date/time, ip address, terminal, command)
• inetLatency: now you can provide a host against which you want to test latency (default is 8.8.8.8)
• getDynamicData: changed order of parameters (callback - if provided - is now the last one): getDynamicData(srv, network, callback)
• getAllData: changed order of parameters (callback - if provided - is now the last one): getAllData(srv, network, callback)

New Functions

• FreeBSD support: for some basic functions (new in version 3.34 ff)
• diskLayout: returns hard disk layout (new in version 3.23)
• memLayout: returns memory chip layout (new in version 3.23)
• Windows support: for some basic functions (new in version 3.17 ff)
• cpuCache: returns CPU cache (L1, L2, L3) sizes (new in version 3.14)
• cpuFlags: returns CPU flags (new in version 3.14)
• currentLoad.cpus: returns current load per cpu/core in an array (new in version 3.14)
• shell: returns standard shell e.g. /bin/bash (new in version 3.13)
• blockDevices: returns array of block devices like disks, partitions, raids, roms (new in version 3.10)
• dockerContainerProcesses: returns processes for a specific docker container (new in version 3.8)
• versions: returns object of versions - kernel, ssl, node, npm, ...(new in version 3.6)
• graphics: returns arrays of graphics controllers and displays (new in version 3.5)
• networkInterfaceDefault: returns default network interface (new in version 3.4)
• processes: now returns also a process list with all process details (new in version 3.3)
• battery: retrieves battery status and charging level (new in version 3.2)
• dockerContainers: returns a list of all docker containers (new in version 3.1)
• dockerContainerStats: returns statistics for a specific docker container (new in version 3.1)
• dockerAll: returns a list of all docker containers including their stats (new in version 3.1)
• disksIO: returns overall diskIO and IOPS values for all mounted volumes (new in version 3.0)

Bug Fixes / improvements

• improvement cpuTemperature - works now also on Raspberry Pi
• bugfix disksIO - on OSX read and write got mixed up
• several bug fixes (like assess errors in cpuCurrentspeed, potentially incorrect results in users, ...)
• testet on even more platforms and linux distributions

Be aware, that the new version 3.x is NOT fully backward compatible to version 2.x ...

Major (breaking) Changes - Version 2

There had been a lot of changes in version 2 of systeminformation! Here is a quick overview (for those who come from version 1):

New Functions

• version: returns systeminformation version (semver) of this library
• system: hardware info (manufacturer, product/model name, version, serial, uuid)
• networkConnections: number of active connections
• inetLatency: latency in ms to external resource (internet)
• getStaticData: returns on json object with static data at once (OS, CPU, Network Interfaces - they should not change until restarted)
• getDynamicData: returns on json object with all dynamic data at once (e.g. for monitoring agents)
• getAllData: returns on json object with all data (static and dynamic) at once

Renamed Functions (now all camelCase)

• osinfo: renamed to osInfo
• cpu_currentspeed: renamed to cpuCurrentspeed
• cpu_temperature: renamed to cpuTemperature
• fs_size: renamed to fsSize
• fs_speed: renamed to fsStats
• network_interfaces: renamed to networkInterfaces
• network_speed: renamed to networkStats
• network_connections: renamed to networkConnections
• currentload: renamed to currentLoad
• fullload: renamed to fullLoad
• processload: renamed to processLoad
• checksite: renamed to inetChecksite

Function Changes

• cpu_temperature/cpuTemperature: -1 is new default (and indicates that non sensors are installed)
• cpu_temperature/cpuTemperature: new result max which returns max temperature of all cores
• cpu_currentspeed/cpuCurrentspeed: now in GHz
• cpu: splitted manufacturer (e.g. Intel) and brand (e.g. Core 2 Duo)
• network_speed/networkStats: now better support for OS X (also support for operstate)
• network_speed/networkStats: overall received and transferred bytes (rx, tx)
• mem: now better support for OS X (also support for swaptotal, swapused, swapfree)
• fs_size/fsSize: use-values now in % (0 - 100% instead of 0 - 1)
• fs_speed/fsStats: now also full support for OS X
• checksite/inetChecksite: new result structure - see command reference
• checksite/inetChecksite: ms (former response_ms): -1 if not ok

Other changes

• osx-temperature-sensor: now added as an optional dependency
• no more external dependencies: request is not longer needed
• where possible results are now integer or float values (instead of strings) because it is easier to calculate with numbers ;-)