How to fix DeprecationWarning: punycode module is deprecated (use URLSearchParams instead) in Node.js

Node.jsBEGINNERLOWUpdated Dec 9, 2025· 195 views

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.

Quick fix

Fixes DEP0040

npm ls punycode
  1. Identify which package is using punycode
  2. Update dependencies to latest versions
  3. Replace direct punycode usage with WHATWG URL API
  4. Use npm overrides for transitive dependencies
node.js — error
npm ls punycode
DeprecationWarning: punycode module is deprecated (use URLSearchParams instead)

What this error means

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.

Typical symptoms

  • Console shows "DeprecationWarning: The punycode module is deprecated" during application startup or runtime
  • Warning appears when running npm scripts or starting your Node.js server
  • Application continues to work normally but logs deprecation warnings
  • Warning may appear even if you're not directly using punycode in your code

Common causes

  1. Your code directly imports the built-in punycode module with require('punycode')
  2. Dependencies like old versions of whatwg-url, tr46, node-fetch, or ajv use the built-in punycode module
  3. Using Node.js version 21 or higher, which made punycode a runtime deprecation
  4. Legacy URL encoding code that hasn't been updated to use the WHATWG URL API

How to fix "DeprecationWarning: punycode module is deprecated (use URLSearchParams instead)"

1Identify which package is using punycode

First, determine if your code or a dependency is causing the warning:

bash
npm ls punycode

This shows which packages in your dependency tree are using punycode. Common culprits include whatwg-url, tr46, node-fetch, and ajv.

2Update dependencies to latest versions

Update dependencies that have removed their punycode dependency. Many packages like whatwg-url v14+ no longer use punycode:

bash
npm update

Check if specific packages have newer versions:

bash
npm outdated

Update problematic packages manually:

bash
npm install whatwg-url@latest
3Replace direct punycode usage with WHATWG URL API

If your code directly uses punycode for URL encoding, replace it with the native WHATWG URL API:

Before (deprecated):

javascript
const punycode = require('punycode');
const encoded = punycode.toASCII('münchen.de');

After (recommended):

javascript
const { domainToASCII } = require('url');
const encoded = domainToASCII('münchen.de');

Or use the URL constructor which handles punycode automatically:

javascript
const url = new URL('https://münchen.de/path');
console.log(url.hostname); // Automatically encoded to ASCII
4Use npm overrides for transitive dependencies

If a dependency hasn't updated yet, force a newer version using npm overrides in package.json:

json
{
  "overrides": {
    "whatwg-url": "^14.0.0"
  }
}

Then reinstall:

bash
npm install

For Yarn, use resolutions:

json
{
  "resolutions": {
    "whatwg-url": "^14.0.0"
  }
}
5Migrate to userland punycode package if needed

If you need punycode functionality that isn't covered by the WHATWG URL API, use the userland punycode package:

bash
npm install punycode

Important: Use require('punycode/') with a trailing slash to import the userland module instead of the built-in one:

javascript
// This imports the deprecated built-in module (wrong):
const punycode = require('punycode');

// This imports the userland module (correct):
const punycode = require('punycode/');

Advanced notes

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:

bash
node --no-deprecation your-script.js

Performance 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.

Frequently asked questions

What does "DEP0040" mean?
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). 0 (October 2023).
How do I fix "DEP0040"?
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.
What causes "DEP0040"?
Your code directly imports the built-in punycode module with require('punycode') Dependencies like old versions of whatwg-url, tr46, node-fetch, or ajv use the built-in punycode module Using Node.js version 21 or higher, which made punycode a runtime deprecation
Is the "DEP0040" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading