IDNA — Internationalized Domain Names in Applications

Warnings

• breaking idna v3.0 dropped Python 2 support entirely. Use 'idna<3' in requirements for Python 2 applications.
  Fix: Pin to idna<3 for Python 2. For Python 3, use idna>=3.0.
• breaking The string codec name is 'idna2008', NOT 'idna'. After 'import idna.codec', use str.encode('idna2008'). Using 'idna' as the codec name silently invokes the stdlib IDNA 2003 codec and produces wrong results for many domains.
  Fix: import idna.codec; domain.encode('idna2008')
• breaking Dot-prefixed domains (e.g. '.example.com') are no longer accepted as valid. They raise IDNAError. Strip leading dots before calling encode().
  Fix: domain = domain.lstrip('.')
• deprecated The 'transitional' keyword argument to encode() no longer has any effect because Unicode 16.0.0 removed transitional processing. It will be removed in a future release.
  Fix: Remove the transitional=True/False argument from all encode() calls.
• gotcha Uppercase and mixed-case labels raise InvalidCodepoint in strict (default) IDNA 2008 mode. Pass uts46=True to enable UTS #46 case-folding, which silently lowercases the input before conversion.
  Fix: idna.encode(domain, uts46=True) for user-supplied domains; idna.encode(domain) only for already-normalized lowercase labels.
• gotcha CVE-2024-3651 (fixed in v3.7): specially crafted inputs to encode() caused catastrophic ReDoS-style CPU consumption. Any deployment on untrusted input must be on >=3.7.
  Fix: Upgrade to idna>=3.7 immediately if processing untrusted domain names.
• gotcha Emoji and symbol domains are expressly prohibited by IDNA 2008 and will raise an exception. There is no flag to allow them. Fall back to encodings.idna (IDNA 2003) only as a last resort for legacy emoji domains.
  Fix: Catch IDNAError and fall back to encodings.idna only when emoji/symbol domain support is explicitly required.

Install

• pip install idna PyPI

Imports

• encode

  import idna; idna.encode('例え.jp')

  encodings.idna is the stdlib IDNA 2003 module; it produces different (incorrect by modern standards) results. Use the idna package instead.
• IDNAError

  from idna.core import InvalidCodepoint

  All conversion errors inherit from idna.IDNAError; more specific subclasses are idna.IDNABidiError, idna.InvalidCodepoint, and idna.InvalidCodepointContext.
• codec

  import idna.codec; '例え.jp'.encode('idna2008')

  The registered codec name changed to 'idna2008' (not 'idna') because overriding the system 'idna' codec was broken. Using 'idna' as the codec name will invoke the stdlib IDNA 2003 codec, not this library.
• compat

  import idna.compat

  Drop-in shim that maps encodings.idna function signatures (ToASCII/ToUnicode) to IDNA 2008 equivalents. Substitute the import and no other code changes are needed.

Quickstart

Encode a Unicode domain to ASCII-compatible encoding (A-label) and decode back; handle mixed-case input with uts46=True.

import idna

# Encode a Unicode domain to ACE/A-label bytes
acе_label = idna.encode('ドメイン.テスト')
print(ace_label)          # b'xn--eckwd4c7c.xn--zckzah'

# Decode ACE back to Unicode
unicode_domain = idna.decode('xn--eckwd4c7c.xn--zckzah')
print(unicode_domain)     # ドメイン.テスト

# Capital letters are rejected by IDNA 2008 strict mode;
# pass uts46=True to enable UTS #46 case-folding pre-processing.
ace_uts46 = idna.encode('Königsgäßchen', uts46=True)
print(ace_uts46)          # b'xn--knigsgchen-b4a3dun'

# Per-label helpers
print(idna.alabel('例え'))   # b'xn--r8jz45g'
print(idna.ulabel(b'xn--r8jz45g'))  # 例え

# Codec interface (import idna.codec to register it first)
import idna.codec
encoded = '例え.jp'.encode('idna2008')   # codec name is 'idna2008', NOT 'idna'
print(encoded)            # b'xn--r8jz45g.jp'

# Error handling
try:
    idna.encode('Königsgäßchen')   # strict mode rejects uppercase
except idna.core.InvalidCodepoint as e:
    print(f'Encoding error: {e}')