'The punycode module is deprecated' warning on every Node.js run
(node:12345) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.Short answer
The warning is Node.js telling you that something calls its built-in punycode module, deprecated as DEP0040. It is not an error and the app still runs. Find the caller with --trace-deprecation, update that package so it uses a userland punycode package, and only hide the warning when you cannot.
Fix it fast
1Find out which cause you have
Print the stack of the warning so you can see which file asked for the module.
node --trace-deprecation app.js2Match what you see, then jump to its fix
- 1
The trace points into node_modules, for example an old url, whatwg-url or tr46 copyA dependency still requires the built-in punycodeFix - 2
The trace points at a file in your project, not node_modulesYour own code imports node:punycodeFix - 3
The trace points to a package you cannot change yetYou only want a quiet log while waiting for a dependency fixFix
- 1
What does the error look like?
(node:12345) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.(Use `node --trace-deprecation ...` to show where the warning was created)
Cause 1 of 3
A dependency still requires the built-in punycode
1Check
Application-level deprecations from node_modules are normally hidden in newer Node.js 22 and 23 releases. If you still see the warning, an older Node.js is running, or your own code is involved. Use pending deprecation mode to list the dependency callers.
node -v
node --pending-deprecation --trace-deprecation app.js2Fix
Update the package named in the trace to a release that does not use the built-in module. Where the module is a deep transitive dependency, update its parent or add an override in the root package.json.
npm update package-from-trace
npm ls punycode3Verify
Run again with tracing on; the warning does not print.
node --trace-deprecation app.jsConfirmed by nodejs.org
Cause 2 of 3
Your own code imports node:punycode
1Check
Search your source for the built-in module name.
grep -rn "punycode" src/ --include=*.js --include=*.ts2Fix
The Node.js docs for DEP0040 say to use a userland alternative. Pick a maintained punycode package from the npm registry, add it to your dependencies, and import it by its package name instead of the built-in module.
// before
const punycode = require('node:punycode');
// after: install your chosen package, then require it by that name3Verify
Start the app; the DEP0040 line is gone.
node app.jsConfirmed by nodejs.org
Cause 3 of 3
You only want a quiet log while waiting for a dependency fix
1Check
Deprecation warnings can be turned off for one process with a Node.js flag. This also hides other deprecations, so use it with care.
node --no-deprecation app.js2Fix
Set it only for the affected command, and keep tracing available.
NODE_OPTIONS=--no-deprecation npm start3Verify
The log is quiet and the app behaves the same.
NODE_OPTIONS=--no-deprecation npm startConfirmed by nodejs.org
How do I stop it coming back?
- Run npm outdated now and then and update the packages that appear in deprecation traces.
- Run the test suite with --throw-deprecation in CI so new deprecated calls in your own code fail early.
- Do not leave --no-deprecation in production scripts for good; you will miss the next real warning.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Back end
ng serve says it cannot determine the project or target
Cannot determine project for command.
The Angular CLI looked through angular.json for a project that defines the target you asked for (serve, build, test) and found none, or found several and could not pick one.
3 causes, each with a fixBack end
ng fails with Cannot find module @angular/cli/bin/ng
Cannot find module '@angular/cli/bin/ng'
The ng command is the entry point to the Angular CLI package.
2 causes, each with a fixBack end
Angular app shows 'Cannot GET /' when served by a Node.js server
Cannot GET /dashboard
Cannot GET / is Express saying no route or file matches the request.
3 causes, each with a fixBack end
ng serve cannot find the dev-server builder package
Could not find the implementation for builder @angular/build:dev-server
The builder named in angular.json (for example @angular-devkit/build-angular:dev-server) is looked up as an npm package starting from the workspace root.
3 causes, each with a fixBack end
Angular build says it cannot resolve '@angular/localize/init'
Can't resolve '@angular/localize/init' in '/usr/src/app/src'
The build imports @angular/localize, and that package is not in node_modules.
2 causes, each with a fixBack end
The command npm run build -- --prod exited with code 1 (Angular)
The command "npm run build -- --prod" exited with code 1
Exit code 1 only says the build failed; the real message is above it.
2 causes, each with a fix