fqdn

library1.5.1pypypi✓ verified 26d ago

The `fqdn` Python library, currently at version 1.5.1, provides RFC-compliant validation and manipulation of Fully Qualified Domain Names (FQDNs). Its primary purpose is to ensure that domain names adhere to Internet Engineering Task Force specifications like RFC 1123, making them suitable for traditional internet hostname usage. This is often a stricter subset of what modern web browsers accept. The library typically sees updates in response to specification clarifications or bug fixes, though major releases are infrequent.

serialization http-networking

pip install fqdn

github ↗package ↗

INSTALL

IMPORT

SIG · FQDN

fqdn

serializationpythonv1.5.1

Install

1.6s avg

Import

—

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 v1.5.1 · 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.000s · 17.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.000s · 18MB

16MB installed

● package 16MB

Code

Verified usage

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

FQDN

✓ from fqdn import FQDN

✗ import fqdn

The primary class for FQDN validation is `FQDN`.

Instantiate the `FQDN` class with a domain string and use its `is_valid` property to check for RFC compliance. Other properties like `absolute` and `relative` provide different representations.

from fqdn import FQDN domain_name_valid = 'example.com' domain_name_invalid = 'localhost' fqdn_obj_valid = FQDN(domain_name_valid) fqdn_obj_invalid = FQDN(domain_name_invalid) print(f"'{domain_name_valid}' is valid: {fqdn_obj_valid.is_valid}") print(f"Absolute form: {fqdn_obj_valid.absolute}") print(f"'{domain_name_invalid}' is valid: {fqdn_obj_invalid.is_valid}") # Example with relaxed constraints (though specific params aren't directly exposed in quickstart) # fqdn_obj_relaxed = FQDN('example', allow_single_label=True) # Illustrative, actual param might differ or be via a different method # print(f"'example' is valid (relaxed): {fqdn_obj_relaxed.is_valid}")

Debug

Known issues

gotchaThe `fqdn` library validates against strict RFC standards (e.g., RFC 1123, 1035), which are often more restrictive than what modern web browsers or certain Certificate Authorities (like Let's Encrypt) might accept as a valid domain name. This can lead to domains that work in browsers being rejected by `fqdn`.

fix

Understand that `fqdn` prioritizes strict RFC compliance. If browser-like permissiveness is needed, custom relaxation of rules or an alternative library may be required.

affects: All versions

gotchaBy default, the `fqdn` library requires FQDNs to have a minimum of two labels (e.g., 'example.com' is valid, but 'example' is not). This is an explicit default constraint enabled to prevent breaking backwards compatibility with earlier versions.

fix

If single-label hostnames or other non-standard formats are expected, consult the library's source or documentation for configuration options to relax specific constraints.

affects: All versions

gotchaDo not confuse this library (`fqdn`) with Python's built-in `socket.getfqdn()`. The `fqdn` library is designed for *validating arbitrary string inputs* as FQDNs, whereas `socket.getfqdn()` is used for *retrieving the Fully Qualified Domain Name of the local machine*.

fix

Use `from fqdn import FQDN` for external string validation. Use `import socket; socket.getfqdn()` only when inquiring about the local system's hostname resolution.

affects: All versions

gotchaThe `fqdn` library primarily validates the *syntactic structure* of an FQDN according to RFCs. It does not perform live DNS lookups or validate against dynamic lists like IANA TLDs or the Public Suffix List. Therefore, a syntactically valid FQDN might not correspond to a *registrable* or *existing* domain on the internet.

fix

For validation against actual registrable domains or live existence, combine `fqdn` with other libraries that perform DNS lookups (e.g., `dnspython`) or consult public suffix lists (e.g., `fqdn-parser`).

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'fqdn'

The `fqdn` library has not been installed in your Python environment.

fix

Install the library using pip: `pip install fqdn`

fqdn.FQDN validation fails for domain with underscore

The `fqdn` library, by default, enforces strict RFC compliance (e.g., RFC 1123) for FQDNs, which prohibits underscores in domain labels.

fix

To allow underscores, you need to instantiate `FQDN` with the `allow_underscore` parameter set to `True`: `from fqdn import FQDN; domain = FQDN('my_host.example.com', allow_underscore=True); print(domain.is_valid)`

fqdn.FQDN is_valid returns False for short hostname like 'localhost'

The `fqdn` library, adhering to RFCs, requires a fully qualified domain name with at least two labels (e.g., 'hostname.domain.com'). A single-label hostname or a hostname without a top-level domain (TLD) is considered invalid by default.

fix

To allow short hostnames (single-label or without a TLD), instantiate `FQDN` with the `allow_cached_without_dot` or `allow_non_canonical` (for broader relaxations) parameters set to `True`: `from fqdn import FQDN; domain = FQDN('localhost', allow_cached_without_dot=True); print(domain.is_valid)`

fqdn.FQDN validation fails for numeric TLD (e.g., 'example.123')

RFC specifications for FQDNs typically require the top-level domain (TLD) to contain only alphabetic characters, not numbers.

fix

Ensure the TLD of your domain name consists solely of alphabetic characters to comply with strict RFC standards. If numeric TLDs are needed for specific internal or non-standard uses, consider using the `allow_non_canonical` flag, but be aware this deviates from strict RFC compliance: `from fqdn import FQDN; domain = FQDN('example.123', allow_non_canonical=True); print(domain.is_valid)`

Upgrade

Version history

1.5.1latest on PyPI · released Mar 11, 2021

Audit

Dependencies

pythonrequiredRuntime environment

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/ypcrts/fqdn ↗

packagehttps://pypi.org/project/fqdn/ ↗