Node.js shows a deprecation warning when code uses the built-in punycode module. This module has been deprecated since Node.js v7 and became a runtime deprecation in v21, warning that it will be removed in a future major version.
This deprecation warning appears when Node.js detects that your code or one of your dependencies is importing the built-in `punycode` module. The punycode module handles internationalized domain names by converting Unicode characters to ASCII-compatible encoding (Punycode). While the punycode module was deprecated since Node.js v7.0.0 (October 2016), it only became a visible runtime deprecation starting with Node.js v21.0.0 (October 2023). This means many developers are seeing this warning for the first time despite using code that has relied on punycode for years. The deprecation is part of Node.js's move toward standardized web APIs. The functionality is still available through userland modules and the WHATWG URL API, which is now the recommended approach for URL encoding operations.
First, determine if your code or a dependency is causing the warning:
npm ls punycodeThis shows which packages in your dependency tree are using punycode. Common culprits include whatwg-url, tr46, node-fetch, and ajv.
Update dependencies that have removed their punycode dependency. Many packages like whatwg-url v14+ no longer use punycode:
npm updateCheck if specific packages have newer versions:
npm outdatedUpdate problematic packages manually:
npm install whatwg-url@latestIf your code directly uses punycode for URL encoding, replace it with the native WHATWG URL API:
Before (deprecated):
const punycode = require('punycode');
const encoded = punycode.toASCII('münchen.de');After (recommended):
const { domainToASCII } = require('url');
const encoded = domainToASCII('münchen.de');Or use the URL constructor which handles punycode automatically:
const url = new URL('https://münchen.de/path');
console.log(url.hostname); // Automatically encoded to ASCIIIf a dependency hasn't updated yet, force a newer version using npm overrides in package.json:
{
"overrides": {
"whatwg-url": "^14.0.0"
}
}Then reinstall:
npm installFor Yarn, use resolutions:
{
"resolutions": {
"whatwg-url": "^14.0.0"
}
}If you need punycode functionality that isn't covered by the WHATWG URL API, use the userland punycode package:
npm install punycodeImportant: Use require('punycode/') with a trailing slash to import the userland module instead of the built-in one:
// This imports the deprecated built-in module (wrong):
const punycode = require('punycode');
// This imports the userland module (correct):
const punycode = require('punycode/');Why the trailing slash matters: Node.js prioritizes built-in modules over npm packages. Using require('punycode/') with a trailing slash forces Node.js to look for a file or directory in node_modules rather than the built-in module.
Dependency update strategy: Check GitHub issues for dependencies that show this warning. Many maintainers have already released updates. For example, whatwg-url versions before v14.0.0 used punycode, but v14+ migrated away from it.
Suppressing the warning (not recommended): You can suppress deprecation warnings with --no-deprecation flag, but this hides important migration signals:
node --no-deprecation your-script.jsPerformance consideration: The WHATWG URL API is generally faster than the old punycode module for URL-related operations since it's implemented in native code.
Timeline: While no specific removal date has been announced, Node.js typically removes deprecated APIs in the next major version after sufficient warning period. Given the deprecation became runtime-visible in v21, expect removal consideration in v22 or later major versions.
Error: EMFILE: too many open files, watch
EMFILE: fs.watch() limit exceeded
Error: Listener already called (once event already fired)
EventEmitter listener already called with once()
Error: Middleware next() called multiple times (next() invoked twice)
Express middleware next() called multiple times
Error: Worker failed to initialize (worker startup error)
Worker failed to initialize in Node.js
Error: EMFILE: too many open files, open 'file.txt'
EMFILE: too many open files