Skip to content

hostname

validators.hostname.hostname(value, /, *, skip_ipv6_addr=False, skip_ipv4_addr=False, may_have_port=True, maybe_simple=True, consider_tld=False, private=None, rfc_1034=False, rfc_2782=False)

Return whether or not given value is a valid hostname.

Examples:

>>> hostname("ubuntu-pc:443")
# Output: True
>>> hostname("this-pc")
# Output: True
>>> hostname("xn----gtbspbbmkef.xn--p1ai:65535")
# Output: True
>>> hostname("_example.com")
# Output: True
>>> hostname("123.5.77.88:31000")
# Output: True
>>> hostname("12.12.12.12")
# Output: True
>>> hostname("[::1]:22")
# Output: True
>>> hostname("dead:beef:0:0:0:0000:42:1")
# Output: True
>>> hostname("[0:0:0:0:0:ffff:1.2.3.4]:-65538")
# Output: ValidationError(func=hostname, ...)
>>> hostname("[0:&:b:c:@:e:f::]:9999")
# Output: ValidationError(func=hostname, ...)

Parameters:

Name Type Description Default
value str

Hostname string to validate.

 required
skip_ipv6_addr bool

When hostname string cannot be an IPv6 address.

 False
skip_ipv4_addr bool

When hostname string cannot be an IPv4 address.

 False
may_have_port bool

Hostname string may contain port number.

 True
maybe_simple bool

Hostname string maybe only hyphens and alpha-numerals.

 True
consider_tld bool

Restrict domain to TLDs allowed by IANA.

 False
private Optional[bool]

Embedded IP address is public if False, private/local if True.

 None
rfc_1034 bool

Allow trailing dot in domain/host name. Ref: RFC 1034.

 False
rfc_2782 bool

Domain/Host name is of type service record. Ref: RFC 2782.

 False

Returns:

Type Description
Literal[True]

If value is a valid hostname.
ValidationError

If value is an invalid hostname.
Source code in src/validators/hostname.py 
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
@validator
def hostname(
    value: str,
    /,
    *,
    skip_ipv6_addr: bool = False,
    skip_ipv4_addr: bool = False,
    may_have_port: bool = True,
    maybe_simple: bool = True,
    consider_tld: bool = False,
    private: Optional[bool] = None,  # only for ip-addresses
    rfc_1034: bool = False,
    rfc_2782: bool = False,
):
    """Return whether or not given value is a valid hostname.

    Examples:
        >>> hostname("ubuntu-pc:443")
        # Output: True
        >>> hostname("this-pc")
        # Output: True
        >>> hostname("xn----gtbspbbmkef.xn--p1ai:65535")
        # Output: True
        >>> hostname("_example.com")
        # Output: True
        >>> hostname("123.5.77.88:31000")
        # Output: True
        >>> hostname("12.12.12.12")
        # Output: True
        >>> hostname("[::1]:22")
        # Output: True
        >>> hostname("dead:beef:0:0:0:0000:42:1")
        # Output: True
        >>> hostname("[0:0:0:0:0:ffff:1.2.3.4]:-65538")
        # Output: ValidationError(func=hostname, ...)
        >>> hostname("[0:&:b:c:@:e:f::]:9999")
        # Output: ValidationError(func=hostname, ...)

    Args:
        value:
            Hostname string to validate.
        skip_ipv6_addr:
            When hostname string cannot be an IPv6 address.
        skip_ipv4_addr:
            When hostname string cannot be an IPv4 address.
        may_have_port:
            Hostname string may contain port number.
        maybe_simple:
            Hostname string maybe only hyphens and alpha-numerals.
        consider_tld:
            Restrict domain to TLDs allowed by IANA.
        private:
            Embedded IP address is public if `False`, private/local if `True`.
        rfc_1034:
            Allow trailing dot in domain/host name.
            Ref: [RFC 1034](https://www.rfc-editor.org/rfc/rfc1034).
        rfc_2782:
            Domain/Host name is of type service record.
            Ref: [RFC 2782](https://www.rfc-editor.org/rfc/rfc2782).

    Returns:
        (Literal[True]): If `value` is a valid hostname.
        (ValidationError): If `value` is an invalid hostname.
    """
    if not value:
        return False

    if may_have_port and (host_seg := _port_validator(value)):
        return (
            (_simple_hostname_regex().match(host_seg) if maybe_simple else False)
            or domain(host_seg, consider_tld=consider_tld, rfc_1034=rfc_1034, rfc_2782=rfc_2782)
            or (False if skip_ipv4_addr else ipv4(host_seg, cidr=False, private=private))
            or (False if skip_ipv6_addr else ipv6(host_seg, cidr=False))
        )

    return (
        (_simple_hostname_regex().match(value) if maybe_simple else False)
        or domain(value, consider_tld=consider_tld, rfc_1034=rfc_1034, rfc_2782=rfc_2782)
        or (False if skip_ipv4_addr else ipv4(value, cidr=False, private=private))
        or (False if skip_ipv6_addr else ipv6(value, cidr=False))
    )