{"id":11600,"library":"punycode","title":"Punycode Converter","description":"Punycode.js is a robust JavaScript library for converting Unicode strings to Punycode and vice-versa, strictly adhering to RFC 3492 (Punycode) and RFC 5891 (IDNA2008). It provides low-level functions for encoding and decoding individual string parts, as well as higher-level utilities for processing entire domain names and email addresses. The current stable version is 2.3.1. While previously bundled with Node.js up to v7, the userland module (`npm install punycode`) now specifically targets modern Node.js v6+ environments and browsers supporting ES2015+ features. Version 1.4.1 remains available for broader compatibility with older runtimes like Rhino, Ringo, and Narwhal, offering the same functionality with a UMD build. The project is actively maintained with periodic releases.","status":"active","version":"2.3.1","language":"javascript","source_language":"en","source_url":"https://github.com/mathiasbynens/punycode.js","tags":["javascript","punycode","unicode","idn","idna","dns","url","domain"],"install":[{"cmd":"npm install punycode","lang":"bash","label":"npm"},{"cmd":"yarn add punycode","lang":"bash","label":"yarn"},{"cmd":"pnpm add punycode","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"In Node.js, `require('punycode')` refers to the deprecated built-in module. Always use `require('punycode/')` (with the trailing slash) to import the userland npm package.","wrong":"const punycode = require('punycode');","symbol":"punycode","correct":"const punycode = require('punycode/');"},{"note":"The library primarily exposes a default object with all its methods. While it ships as both CommonJS and ES Modules, direct named imports are not the intended pattern for the main functions.","wrong":"import { decode, encode } from 'punycode';","symbol":"punycode","correct":"import punycode from 'punycode';"},{"note":"Methods like `toASCII` are properties of the default `punycode` object, not direct named exports.","wrong":"import { toASCII } from 'punycode';\ntoASCII('mañana.com');","symbol":"toASCII","correct":"const punycode = require('punycode/');\npunycode.toASCII('mañana.com');"}],"quickstart":{"code":"const punycode = require('punycode/');\n\n// Encode a Unicode domain name to Punycode\nconst unicodeDomain = 'mañana.com';\nconst punycodeDomain = punycode.toASCII(unicodeDomain);\nconsole.log(`Unicode domain: ${unicodeDomain}`);\nconsole.log(`Punycode domain: ${punycodeDomain}`);\n\n// Decode a Punycode domain name back to Unicode\nconst decodedUnicodeDomain = punycode.toUnicode(punycodeDomain);\nconsole.log(`Decoded Unicode domain: ${decodedUnicodeDomain}`);\n\n// Encode/decode individual string parts\nconst unicodePart = '☃-⌘';\nconst punycodePart = punycode.encode(unicodePart);\nconsole.log(`Unicode part: ${unicodePart}`);\nconsole.log(`Punycode part: ${punycodePart}`);\n\nconst decodedUnicodePart = punycode.decode(punycodePart);\nconsole.log(`Decoded Unicode part: ${decodedUnicodePart}`);","lang":"javascript","description":"This quickstart demonstrates how to encode and decode internationalized domain names (IDN) and individual Unicode string parts using `punycode.js`."},"warnings":[{"fix":"For compatibility with older runtimes (Rhino, Ringo, Narwhal, older browsers), use `punycode` v1.4.1. Otherwise, ensure your environment supports ES2015+.","message":"Version 2.0.0 and above dropped support for older JavaScript environments. It targets Node.js v6+ and modern browsers, requiring ES2015+ features.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Always use `require('punycode/')` (with the trailing slash) to explicitly load the npm package. Avoid `require('punycode')` if you intend to use the userland module, as it will load the built-in one.","message":"In Node.js, the userland `punycode` package from npm can conflict with Node.js's deprecated built-in `punycode` module.","severity":"gotcha","affected_versions":">=0.6.2"},{"fix":"Install the `punycode` npm package via `npm install punycode` and import it using `require('punycode/')` or `import punycode from 'punycode';`.","message":"The `punycode` module bundled with Node.js itself has been deprecated (soft-deprecated from v7) and is no longer recommended for new projects. It is advised to use the standalone npm package.","severity":"deprecated","affected_versions":">=7.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"If you've installed the `punycode` npm package, ensure you are importing it with a trailing slash: `const punycode = require('punycode/');`.","cause":"Attempting to `require('punycode')` in a Node.js environment where the built-in module is not available or has been overridden by the npm package without the correct import path.","error":"Error: Cannot find module 'punycode'"},{"fix":"Upgrade your Node.js version to v6 or higher, or use a modern browser. If backward compatibility for older runtimes is essential, downgrade to `punycode` v1.4.1.","cause":"Using `punycode` v2.0.0 or higher in an environment that does not fully support ES2015+ features.","error":"SyntaxError: Unexpected token ... (or similar ES2015+ syntax error)"}],"ecosystem":"npm"}