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

Node.jsBEGINNERLOW

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

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/');

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

What this error means

Typical symptoms

Common causes

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

Advanced notes

Related errors

Official resources & further reading