Node.js Reference ยท HTTP, HTTPS, net, TLS, dgram and dns
Node.js dns.lookup() method
Reference for dns.lookup() in Node.js: resolve a host name with the operating system resolver, choose IPv4 or IPv6, get all addresses, and handle errors.
dns.lookup() turns a host name such as localhost or example.org into an IP address. It asks the operating system to do the work, by calling the same getaddrinfo routine that every other program on the machine uses. That means it honors the hosts file, the system's search domains and its resolver configuration.
This is the function Node itself uses when you call net.connect(), http.request() or fetch() with a host name. It is not a pure DNS client: it can return answers that never touched a DNS server (for example a line from /etc/hosts). To send real DNS queries and read record types, use dns.resolve() instead.
import dns from 'node:dns'; dns.lookup('localhost', { family: 4 }, (err, address, family) => { console.log(address, family); // 127.0.0.1 4 });
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
dns.lookup(hostname[, options], callback) // callback(err, address, family) when options.all is false // callback(err, addresses) when options.all is true dnsPromises.lookup(hostname[, options]): Promise<{ address: string, family: 4 | 6 }> dnsPromises.lookup(hostname, { all: true }): Promise<Array<{ address: string, family: 4 | 6 }>>
| Name | Description |
|---|---|
hostname |
The name to resolve. An IP address string is returned unchanged. |
options |
An integer (4, 6 or 0) as a shortcut for family, or an object (below). |
options.family |
4, 6 or 0 (any, the default). The strings 'IPv4' and 'IPv6' are accepted too. |
options.hints |
Flags for getaddrinfo, combined with ` |
options.all |
true returns every address instead of the first one. |
options.order |
'verbatim', 'ipv4first' or 'ipv6first'. Overrides the default from dns.setDefaultResultOrder(). |
options.verbatim |
Older boolean form of order; prefer order. |
callback |
Required for the callback API. |
Returns: nothing for the callback form; a promise for the dns/promises form.
Errors: the error object has code set to a getaddrinfo code such as ENOTFOUND (no such name) or EAI_AGAIN (a temporary failure, often no network), plus hostname and syscall: 'getaddrinfo'. Invalid arguments throw synchronously from the callback form with ERR_INVALID_ARG_VALUE or ERR_INVALID_ARG_TYPE; the promise form rejects with the same codes.
Usage notes
- It runs on the libuv thread pool, not on the event loop. Each call occupies one of four threads by default (
UV_THREADPOOL_SIZE). A burst of slow lookups can delay file-system and crypto work that shares the pool. - It is not DNS-only.
/etc/hosts, mDNS and NSS plugins may answer. This is whylocalhostworks even without a network, and why results can differ fromdigornslookup. - Order matters. Since Node 17 the default result order is
verbatim: addresses come back in the order the resolver returned them, so an IPv6 address may come first. Useorder: 'ipv4first'or afamilyfilter if your server only listens on IPv4. - No caching. Node does not cache answers. The OS or a local resolver might, but a hot code path that connects often should reuse sockets (keep-alive agents) instead of looking up every time.
- Prefer
all: truefor connecting. With every address in hand you can try the next one when the first fails.net.connect()does this for you whenautoSelectFamilyis on (the default since Node 20). - Not interchangeable with
resolve.lookup()accepts IP literals and consults the hosts file;resolve*()does neither, and it fails onlocalhostunless the DNS server knows it.