Registry / http-networking / freewhois

freewhois

JSON →
library1.3.8jsnpmunverified

freewhois is a Node.js client designed for retrieving WHOIS information by querying the IANA RDAP DNS database. It provides a free and programmatic way to perform domain lookups. The current stable version is 1.3.8. While a specific release cadence isn't detailed, the TLD list is noted as being updated regularly (last on 11/2/2025), suggesting ongoing maintenance. Its key differentiator is leveraging the IANA RDAP database directly, offering a straightforward, free API for WHOIS queries without relying on external, potentially rate-limited, third-party services. It supports both programmatic use in JavaScript/TypeScript projects and includes a command-line interface for quick lookups, making it versatile for both developers and system administrators.

http-networking
npm install freewhois
github ↗package ↗
INSTALL
IMPORT
SIG · FREEWHOIS
F
freewhois
http-networkingjavascriptv1.3.8
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

whois
✓ const whois = require('freewhois');
✗ import whois from 'freewhois';
This package primarily targets CommonJS environments as shown in its README, though ESM import should work with proper configuration.
whois
✓ import whois from 'freewhois';
✗ import { whois } from 'freewhois';
The main function is exported as a default export, not a named one. Using named import will result in 'undefined' or a runtime error.
freewhois CLI
✓ npm i freewhois -g freewhois "google.com"
For command-line usage, install globally. The CLI acts as a wrapper for the programmatic API.

Demonstrates how to perform a WHOIS lookup for a domain and handle potential errors using the async/await pattern.

const whois = require('freewhois'); async function performWhoisLookup(domain) { try { console.log(` Looking up WHOIS for: ${domain}`); const data = await whois(domain); console.log(`WHOIS data for ${domain}:`); console.log(JSON.stringify(data, null, 2)); } catch (error) { console.error(`Error looking up WHOIS for ${domain}:`, error.message); if (error.response && error.response.status) { console.error(`HTTP Status: ${error.response.status}`); } } } // Example usage for a well-known domain performWhoisLookup('google.com'); // Example for a common TLD performWhoisLookup('example.com'); // Example for a domain that likely does not exist, to demonstrate error handling performWhoisLookup('nonexistent-domain-1234567890.xyz');
freewhois --version
Debug
Known issues
gotchaThe package relies on a list of TLDs sourced from iana.org. This list is updated manually. If you are experiencing issues with new TLDs or incorrect lookups, your local TLD list might be outdated.
fix
Run `npm run update-tlds` in your project directory (if installed locally) or manually update the package if installed globally, to refresh the TLD data.
affects: >=1.0.0
gotchaWHOIS lookups involve external network requests to various RDAP servers. Network connectivity issues, DNS resolution problems, or temporary unavailability of specific RDAP servers can cause lookups to fail.
fix
Implement robust error handling around your `whois` calls and consider retries for transient network failures. Ensure your network configuration allows outbound connections to RDAP servers.
affects: >=1.0.0
gotchaWhile `freewhois` uses IANA RDAP for 'free' lookups, aggressive querying (e.g., thousands of requests per second) can still lead to temporary IP blocking or rate limiting by the individual TLD's RDAP servers.
fix
Introduce sensible delays or rate limiting in your application if performing a high volume of lookups. Cache results where appropriate to reduce redundant requests.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: whois is not a function
Attempting to call `whois` after importing it incorrectly, e.g., using `import { whois } from 'freewhois';` when it's a default export.
fix
For ESM, use `import whois from 'freewhois';`. For CommonJS, use `const whois = require('freewhois');`.
Error: ENOTFOUND <hostname>
The domain name provided is either syntactically invalid, or the DNS lookup for the corresponding RDAP server failed.
fix
Verify the spelling and format of the domain name. Check your network's DNS resolution, and ensure the domain's TLD is recognized and has an active RDAP service.
Error: Domain not found for <domain>
The provided domain name is valid but does not exist or is not registered.
fix
This is expected behavior for unregistered domains. No fix is needed unless you intended to query a registered domain; in that case, double-check the domain's spelling and existence.
Upgrade
Version history
1.3.8latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
4 hits · last 30 days
node
4
Resources
githubhttps://github.com/joshterrill/freewhois ↗
packagehttps://www.npmjs.com/package/freewhois ↗
freewhois — npm install freewhois · libregistry