NODE-PING !Workflow Status

a ping wrapper for nodejs

@last-modified: 2025-09-29

License MIT

(C) Daniel Zelisko

http://github.com/danielzzz/node-ping

Description

node-ping is a simple wrapper for the system ping utility.

Installation

npm install ping

Notes:

* Although it is marked with node >=22, it should technially working in all node version for production purpose. The version is marked for development point of view

Usage

Below are examples extracted from examples

Tradition calls

``js
var ping = require('ping');

var hosts = ['192.168.1.1', 'google.com', 'yahoo.com'];
hosts.forEach(function(host){
ping.sys.probe(host, function(isAlive){
var msg = isAlive ? 'host ' + host + ' is alive' : 'host ' + host + ' is dead';
console.log(msg);
});
});
`

Tradition calls with configuration

`js
var cfg = {
timeout: 10,
// WARNING: -i 2 may not work in other platform like windows
extra: ['-i', '2'],
};

hosts.forEach(function(host){
ping.sys.probe(host, function(isAlive){
var msg = isAlive ? 'host ' + host + ' is alive' : 'host ' + host + ' is dead';
console.log(msg);
}, cfg);
});
`

Promise wrapper

`js
var ping = require('ping');

var hosts = ['192.168.1.1', 'google.com', 'yahoo.com'];

hosts.forEach(function (host) {
ping.promise.probe(host)
.then(function (res) {
console.log(res);
});
});
`

Promise Wrapper with configurable ping options

`js
hosts.forEach(function (host) {
// WARNING: -i 2 argument may not work in other platform like windows
ping.promise.probe(host, {
timeout: 10,
extra: ['-i', '2'],
}).then(function (res) {
console.log(res);
});
});
`

Async-Await

`js
var ping = require('ping');

var hosts = ['192.168.1.1', 'google.com', 'yahoo.com'];

for(let host of hosts){
let res = await ping.promise.probe(host);
console.log(res);
}
`

Async-Await with configurable ping options

`js
var ping = require('ping');

var hosts = ['192.168.1.1', 'google.com', 'yahoo.com'];

for(let host of hosts){
// WARNING: -i 2 argument may not work in other platform like windows
let res = await ping.promise.probe(host, {
timeout: 10,
extra: ['-i', '2'],
});
console.log(res);
}
`


$3

See PingConfig in types/index.d.ts

$3

* For callback based implementation:

See probeCallback in types/ping-sys.d.ts

* For promise based implementation

See PingResponse in types/ping-promise.d.ts

#### Note

* Since ping in this module relies on the ping from underlying platform,
arguments in PingConfig.extra will definitely be varied across different
platforms.

* However, numeric, timeout and min_reply have been abstracted. Values for
them are expected to be cross platform.

* By setting numeric, timeout or min_reply to false, you can run ping
without corresponding arguments.

FAQ

* It does not work with busybox's ping implemetation #89

Try to install package iputils. For example, running apk add iputils

* For questions regarding to the implementation of timeout, and deadline, please checkout discussions in
#101

* For questions regarding to the defintions of host, inputHost, and numeric_host`, please checkout
discussions in #133

Contributing

Before opening a pull request please make sure your changes follow the
[contribution guidelines][1].

[1]: https://github.com/danielzzz/node-ping/blob/master/CONTRIBUTING.md

Contributors

Made with contrib.rocks.