idna

library3.19pypypi✓ verified 25d ago

idna implements the Internationalized Domain Names in Applications (IDNA 2008, RFC 5891) protocol and Unicode IDNA Compatibility Processing (UTS #46) for Python. It is the modern replacement for the built-in encodings.idna module, which only supports the obsolete IDNA 2003 standard. Current version is 3.11 (Python 3.8+); releases are irregular but active, with security patches and Unicode data updates driving most releases.

serialization http-networking

pip install idna

github ↗package ↗changelog ↗

INSTALL

IMPORT

SIG · IDNA

idna

serializationpythonv3.19

Install

1.7s avg

Import

24ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.19 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.028s · 18.3MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.7s · import 0.020s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

encode

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

✗ import encodings.idna; encodings.idna.ToASCII('例え.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')

✗ '例え.jp'.encode('idna')

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.

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}')

Debug

Known issues

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

affects: <3.0

breakingThe 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')

affects: >=3.x

breakingDot-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('.')

affects: >=2.6

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

affects: >=3.10

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

affects: all

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

affects: <3.7

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

affects: all

gotchaA NameError occurred because a variable was used before it was defined. This is a fundamental Python programming error, not specific to the 'idna' library.

fix

Ensure all variables are assigned a value before they are referenced or used in operations (e.g., 'ace_label = idna.encode(domain_name)' instead of just 'print(ace_label)').

affects: all

gotchaA NameError occurred due to an undefined variable 'ace_label'. The Python interpreter's suggestion of 'acе_label' indicates a possible typo or the use of visually similar Unicode characters (e.g., Cyrillic 'е' instead of Latin 'e') in the variable name, leading to the variable being unrecognized.

fix

Ensure all variables are defined before they are used. Carefully check variable names for typos, especially when copying text or dealing with visually similar Unicode characters. It is recommended to use standard ASCII characters for variable names to avoid such confusion.

affects: all

Errors

Common errors & fixes

UnicodeError: encoding with 'idna' codec failed (UnicodeError: label empty or too long)

This error often occurs when a hostname or part of a URL being processed for Internationalized Domain Names (IDNA) violates DNS specifications, such as a label exceeding the maximum length of 63 bytes or containing characters not allowed in domain names.

fix

Ensure that the string passed to the IDNA encoding function represents a valid hostname, not an entire URL, and that each domain label (segment between dots) is no longer than 63 bytes. For URLs, parse out the hostname component before applying IDNA encoding.

LookupError: unknown encoding: idna

This error typically indicates that the 'idna' codec is not properly registered or available in the Python environment, which can happen with embedded Python distributions or when `encodings.idna` isn't implicitly loaded, particularly in multi-threaded applications.

fix

To ensure the `idna` codec is loaded, explicitly import `encodings.idna` (or `import idna` if using the external library) at the application's startup, or perform a no-op encoding/decoding operation like `b''.decode('idna')` or `u''.encode('idna')` early in your code.

idna.IDNAError

This is the base exception for various issues where a domain name string violates the IDNA 2008 or Unicode IDNA Compatibility Processing (UTS #46) specifications, encompassing problems like disallowed characters, incorrect bidirectional text rules (IDNABidiError), or invalid character contexts (InvalidCodepointContext).

fix

Validate the input domain name string against IDNA 2008 and UTS #46 rules, ensuring it adheres to character sets, contextual requirements, and structural rules. Use specific exception handling for subclasses like `idna.InvalidCodepoint` to identify and address the exact violation.

Upgrade

Version history

3.19latest on PyPI · released Aug 18, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

12 hits · last 30 days

node