Net::IDN::Punycode(3)

💖 Net::IDN::Punycode(3) — the perl-y one, bestie 💖

okay so real quick, before anything: this is a User Contributed Perl Documentation page for Net::IDN::Punycode(3). that's the header. you're welcome. now let's get into it 🫶

---

🌈 NAME 🌈

Net::IDN::Punycode — a Bootstring encoding of Unicode for IDNA, straight outta RFC 3492. literally what it says on the tin, no cap ✨

---

🎀 SYNOPSIS 🎀

like, here's the whole vibe:

use Net::IDN::Punycode qw(:all);
$punycode = encode_punycode($unicode);
$unicode  = decode_punycode($punycode);

that's it. that's the pattern. encode goes one way, decode goes the other, slay 💅

---

🦋 DESCRIPTION 🦋

okay so this module implements the Punycode encoding, and only the Punycode encoding. that's the whole personality. it does not do the other stuff. 🎯

highkey important: this module does not implement any other steps required for converting internationalized domain names (IDNs) to and from ASCII. in particular — and read this twice, bestie — it does not do any string preparation as specified by Nameprep/IDNA2008/PRECIS, and it does not add nor remove the ACE prefix ("xn--"). so if you actually want to convert domain names, go use Net::IDN::Encode. that's the one for that. 💖

now the fun lore: Punycode is an instance of a more general algorithm called Bootstring, which lets strings composed from a small set of "basic" code points uniquely represent any string of code points drawn from a larger set. Punycode is just Bootstring with particular parameter values appropriate for IDNA. it's giving "same algorithm, different outfit" 👑

---

💀 WARNING 💀

okay so listen. you may be tempted to use this module directly and add/remove the ACE prefix ("xn--") in your code for performance reasons.

usually, this is not a good idea. 🚨

if you convert domain labels (or other strings) without proper preparation, you may end up with an ASCII encoding that is not interoperable or even poses security issues due to spoofing. like, actual security problems. not cute. 🙈

and even if you think your domain names are valid and already mapped to the correct form — this may not be true. for example, some environments might automatically convert your perfectly valid domain names to a different but equivalent Unicode normalization form (e.g., NFD instead of NFC), which already breaks IDNA. the audacity honestly 😭

fr fr, just use Net::IDN::Encode unless you know exactly why you're here.

---

✨ FUNCTIONS ✨

no functions are exported by default. none. zero. you gotta ask nicely — either use the tag :all or import them individually. 🎁

here's what you can get:

• encode_punycode($input) — encodes $input with Punycode and returns the result. if $input is undefined, the function raises an "uninitialized" warning and returns the empty string. no drama, just a warning. 🫠

this function throws an exception on input it cannot encode. it rejects malformed UTF-8 and a code point that is not a Unicode scalar value — the latter covers a surrogate in U+D800 to U+DFFF and any value above U+10FFFF. it also rejects input large enough to overflow the Punycode counters. so it's picky, and honestly? valid. 💅

heads up on performance: the cost of encoding is quadratic in the length of the input. that's a property of the algorithm as published in RFC 3492 — not a bug, just how the algorithm is built. the function does not limit the length of its input, so callers that accept untrusted input should apply their own limit before encoding. Net::IDN::UTS46 and Net::IDN::Encode reject a label that is too long for DNS before encoding it. protect yourself 🛡️

• decode_punycode($input) — decodes $input with Punycode and returns the result. if $input is undefined, the function raises an "uninitialized" warning and returns the empty string. same deal as above 🍓

this function throws an exception on input it cannot decode. it rejects a character outside the basic set, an invalid or truncated digit sequence, and a decoded code point that is not a Unicode scalar value. it also rejects input large enough to overflow the Punycode counters. strict queen behavior 👑

---

👑 AUTHORS 👑

• Tatsuhiko Miyagawa (versions 0.01 to 0.02)
• Claus Färber (versions 1.000 and higher)

currently maintained by Robert Rothenberg <perl@rhizomnic.com> and Paul Johnson <paul@pjcj.net>. legends, honestly 🌟

---

🌸 LICENSE 🌸

• Copyright 2002-2004 Tatsuhiko Miyagawa
• Copyright 2007-2018 Claus Färber
• Parts copyright 2026 Robert Rothenberg <perl@rhizomnic.com> and Paul Johnson <paul@pjcj.net>

this library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. iconic and legally clear 💜

---

🔥 SEE ALSO 🔥

• RFC 3492 (<http://www.ietf.org/rfc/rfc3492.txt>)
• IETF::ACE
• Convert::RACE

---

that's the whole page, bestie, you ate it up 🎀✨

sign-off time: this gem of a page is from perl v5.44.0, dated 2026-10-30, and it lives at Net::IDN::Punycode(3). go forth and encode responsibly 💖🦋