Node.js DNS Module

What the DNS Module Does

The built-in dns module provides two families of functions: those that use the underlying operating system facilities (like dns.lookup) and those that make actual DNS queries over the network (like dns.resolve4, dns.resolve6, and dns.resolveMx). Understanding the difference matters because they behave differently under the hood, have different performance characteristics, and can return different results in some environments.

dns.lookup() delegates to the operating system's name resolution facilities, which usually means it consults /etc/hosts, NSS configuration, and any local caching resolver before falling back to a remote DNS server. Because it uses libuv's threadpool, it does not directly issue DNS protocol packets, and its behavior can vary slightly between operating systems.

Using dns.lookup

dns.lookup(hostname[, options], callback) resolves a hostname to the first found A (IPv4) or AAAA (IPv6) address. It accepts an options object where you can specify family (4 or 6), and whether you want all matching addresses returned via the all: true option.

const dns = require('dns');

dns.lookup('nodejs.org', (err, address, family) => {
  if (err) throw err;
  console.log('address: %j family: IPv%s', address, family);
});

// Output (example):
// address: "104.20.22.46" family: IPv4

const dns = require('dns');

dns.lookup('nodejs.org', { all: true, family: 0 }, (err, addresses) => {
  if (err) throw err;
  console.log(addresses);
  // [ { address: '104.20.22.46', family: 4 },
  //   { address: '104.20.23.46', family: 4 } ]
});

Using dns.resolve and Its Variants

Unlike dns.lookup, the dns.resolve() family of functions always performs a DNS query on the network, bypassing the operating system's resolver configuration files. This makes them faster in high-throughput scenarios since they don't hit the threadpool, and lets you query specific record types.

• dns.resolve4(hostname, callback) - resolves IPv4 addresses (A records)
• dns.resolve6(hostname, callback) - resolves IPv6 addresses (AAAA records)
• dns.resolveMx(hostname, callback) - resolves mail exchange records
• dns.resolveTxt(hostname, callback) - resolves text records
• dns.resolveCname(hostname, callback) - resolves canonical name records
• dns.resolveNs(hostname, callback) - resolves name server records

const dns = require('dns');

dns.resolveMx('nodejs.org', (err, addresses) => {
  if (err) throw err;
  addresses.forEach((entry) => {
    console.log(`priority ${entry.priority}: ${entry.exchange}`);
  });
});

Reverse Lookups and Promises API

dns.reverse(ip, callback) resolves an IP address to an array of hostnames. Since Node.js 10, the dns module also exposes a Promises API via require('dns').promises, so you can use async/await instead of callbacks throughout.

const dnsPromises = require('dns').promises;

async function resolveHost(hostname) {
  const addresses = await dnsPromises.resolve4(hostname);
  console.log(addresses);

  const hostnames = await dnsPromises.reverse(addresses[0]);
  console.log(hostnames);
}

resolveHost('nodejs.org').catch(console.error);