python-zeroconf API reference

A pure python implementation of multicast DNS service discovery.

Licensed under LGPL-2.1-or-later; see COPYING for details. This file is part of a continuously modified work; modification dates are recorded in the project’s git history.

exception zeroconf.AbstractMethodException

Bases: Error

Exception when a required method is not implemented.

exception zeroconf.BadTypeInNameException

Bases: Error

Exception when the type in a name is invalid.

class zeroconf.DNSQuestionType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

An MDNS question type.

“QU” - questions requesting unicast responses “QM” - questions requesting multicast responses https://datatracker.ietf.org/doc/html/rfc6762#section-5.4

QM = 2

QU = 1

exception zeroconf.Error

Bases: Exception

Base class for all zeroconf exceptions.

exception zeroconf.EventLoopBlocked

Bases: Error

Exception when the event loop is blocked.

This exception is never expected to be thrown during normal operation. It should only happen when the cpu is maxed out or there is something blocking the event loop.

exception zeroconf.IncomingDecodeError

Bases: Error

Exception when there is invalid data in an incoming packet.

exception zeroconf.NamePartTooLongException

Bases: Error

Exception when the name is too long.

exception zeroconf.NonUniqueNameException

Bases: Error

Exception when the name is already registered.

exception zeroconf.NotRunningException

Bases: Error

Exception when an action is called with a zeroconf instance that is not running.

The instance may not be running because it was already shutdown or startup has failed in some unexpected way.

class zeroconf.RecordUpdateListener

Bases: object

Base call for all record listeners.

All listeners passed to async_add_listener should use RecordUpdateListener as a base class. In the future it will be required.

async_update_records(zc: Zeroconf, now: float_, records: list[RecordUpdate]) → None

Update multiple records in one shot.

All records that are received in a single packet are passed to update_records.

This implementation is a compatibility shim to ensure older code that uses RecordUpdateListener as a base class will continue to get calls to update_record. This method will raise NotImplementedError in a future version.

At this point the cache will not have the new records

Records are passed as a list of RecordUpdate. This allows consumers of async_update_records to avoid cache lookups.

This method will be run in the event loop.

async_update_records_complete() → None

Called when a record update has completed for all handlers.

At this point the cache will have the new records.

This method will be run in the event loop.

update_record(zc: Zeroconf, now: float, record: DNSRecord) → None

Update a single record.

This method is deprecated and will be removed in a future version. update_records should be implemented instead.

class zeroconf.ServiceBrowser(zc: Zeroconf, type_: str | list, handlers: ServiceListener | list[Callable[..., None]] | None = None, listener: ServiceListener | None = None, addr: str | None = None, port: int = 5353, delay: int = 10000, question_type: DNSQuestionType | None = None)

Bases: _ServiceBrowserBase, Thread

Threaded browser that fires ServiceListener callbacks as services of the requested types appear, change, and disappear.

async_update_records_complete() → None

Called when a record update has completed for all handlers.

At this point the cache will have the new records.

This method will be run in the event loop.

cancel() → None

Cancel the browser.

done

query_scheduler

run() → None

Run the browser thread.

types: set[str]

zc

class zeroconf.ServiceInfo(type_: str, name: str, port: int | None = None, weight: int = 0, priority: int = 0, properties: bytes | dict | None = None, server: str | None = None, host_ttl: int = 120, other_ttl: int = 4500, *, addresses: Sequence[bytes | str] | None = None, parsed_addresses: list[str] | None = None, interface_index: int | None = None)

Bases: RecordUpdateListener

Everything known about a single service instance.

Holds the instance name, its type, the host server name, port, addresses, priority, weight, and the properties dictionary carried by the TXT record (pass a dict, or bytes to reuse a raw TXT payload). Build one to register a service, or let request or async_request populate one from the network.

property addresses: list[bytes]

IPv4 addresses of this service.

Only IPv4 addresses are returned for backward compatibility. Use addresses_by_version() or parsed_addresses() to include IPv6 addresses as well.

addresses_by_version(version: IPVersion) → list[bytes]

List addresses matching IP version.

Addresses are guaranteed to be returned in LIFO (last in, first out) order with IPv4 addresses first and IPv6 addresses second.

This means the first address will always be the most recently added address of the given IP version.

async_clear_cache() → None

Clear the cache for this service info.

async async_request(zc: Zeroconf, timeout: float, question_type: DNSQuestionType | None = None, addr: str | None = None, port: int = 5353) → bool

Populate this object from the network, returning True on success.

Event loop flavor of request; waits up to timeout milliseconds for the answers to arrive, and addr and port direct the queries at a specific responder instead of the multicast group.

async_update_records(zc: Zeroconf, now: float_, records: list[RecordUpdate_]) → None

Merge a batch of record updates into this object and wake any waiters.

async async_wait(timeout: float, loop: AbstractEventLoop | None = None) → None

Suspend the calling task for timeout milliseconds, or less when new records arrive.

property decoded_properties: dict[str, str | None]

Return properties as strings.

dns_address_nsec(override_ttl: int | None = None) → DNSNsec | None

Return DNSNsec asserting which address types exist, or None if not applicable.

dns_addresses(override_ttl: int | None = None, version: IPVersion = IPVersion.All) → list[DNSAddress]

Return matching DNSAddress from ServiceInfo.

dns_nsec(missing_types: list[int], override_ttl: int | None = None) → DNSNsec | None

Deprecated: use dns_address_nsec instead; missing_types is ignored.

dns_pointer(override_ttl: int | None = None) → DNSPointer

Return DNSPointer from ServiceInfo.

dns_service(override_ttl: int | None = None) → DNSService

Return DNSService from ServiceInfo.

dns_text(override_ttl: int | None = None) → DNSText

Return DNSText from ServiceInfo.

get_address_and_nsec_records(override_ttl: int | None = None) → set[DNSRecord]

Build a set of address records plus an NSEC asserting which address types exist.

get_name() → str

Instance name with the service type stripped.

host_ttl

interface_index

ip_addresses_by_version(version: IPVersion) → list[ZeroconfIPv4Address] | list[ZeroconfIPv6Address]

List ip_address objects matching IP version.

Addresses are guaranteed to be returned in LIFO (last in, first out) order with IPv4 addresses first and IPv6 addresses second.

This means the first address will always be the most recently added address of the given IP version.

key

load_from_cache(zc: Zeroconf, now: float_ | None = None) → bool

Populate the service info from the cache.

This method is designed to be threadsafe.

property name: str

The complete instance name, including the type and domain.

other_ttl

parsed_addresses(version: IPVersion = IPVersion.All) → list[str]

List addresses in their parsed string form.

Addresses are guaranteed to be returned in LIFO (last in, first out) order with IPv4 addresses first and IPv6 addresses second.

This means the first address will always be the most recently added address of the given IP version.

parsed_scoped_addresses(version: IPVersion = IPVersion.All) → list[str]

Equivalent to parsed_addresses, with the exception that IPv6 Link-Local addresses are qualified with %<interface_index> when available

Addresses are guaranteed to be returned in LIFO (last in, first out) order with IPv4 addresses first and IPv6 addresses second.

This means the first address will always be the most recently added address of the given IP version.

port

priority

property properties: dict[bytes, bytes | None]

Return properties as bytes.

request(zc: Zeroconf, timeout: float, question_type: DNSQuestionType | None = None, addr: str | None = None, port: int = 5353) → bool

Populate this object from the network, returning True on success.

Waits up to timeout milliseconds for the answers to arrive; addr and port direct the queries at a specific responder instead of the multicast group.

server

server_key

set_server_if_missing() → None

Set the server if it is missing.

This function is for backwards compatibility.

text

type

weight

exception zeroconf.ServiceNameAlreadyRegistered

Bases: Error

Exception when a service name is already registered.

class zeroconf.Zeroconf(interfaces: Sequence[str | int | tuple[tuple[str, int, int], int]] | InterfaceChoice = InterfaceChoice.All, unicast: bool = False, ip_version: IPVersion | None = None, apple_p2p: bool = False, use_asyncio: bool | None = None)

Bases: QuietLogger

High level mDNS service discovery: register services, browse for them, and resolve their details on the local network.

add_listener(listener: RecordUpdateListener, question: DNSQuestion | list[DNSQuestion] | None) → None

Subscribe a record update listener, optionally scoped to questions; threadsafe.

add_service_listener(type_: str, listener: ServiceListener) → None

Browse for a type and deliver add, remove, and update callbacks to the listener.

async_add_listener(listener: RecordUpdateListener, question: DNSQuestion | list[DNSQuestion] | None) → None

Subscribe a record update listener, optionally scoped to questions; event loop only.

async async_check_service(info: ServiceInfo, allow_name_change: bool, cooperating_responders: bool = False, strict: bool = True) → None

Probe the network for name uniqueness, renaming first when allowed.

async async_get_service_info(type_: str, name: str, timeout: int = 3000, question_type: DNSQuestionType | None = None) → AsyncServiceInfo | None

Look up details for a service on the network from the event loop.

Queries for the given fully qualified type and name, waiting up to timeout milliseconds, and returns a populated AsyncServiceInfo or None when nothing answered in time. question_type forces QM or QU questions instead of the automatic choice.

async_notify_all() → None

Schedule an async_notify_all.

async async_register_service(info: ServiceInfo, ttl: int | None = None, allow_name_change: bool = False, cooperating_responders: bool = False, strict: bool = True) → Awaitable

Announce a service on the network from the event loop.

Returns an awaitable that completes once the announcements have been sent. Prefer setting TTLs on the ServiceInfo over the ttl argument.

async_remove_listener(listener: RecordUpdateListener) → None

Detach a record listener; event loop only, not threadsafe.

async_send(out: DNSOutgoing, addr: str | None = None, port: int = 5353, v6_flow_scope: tuple[()] | tuple[int, int] = (), transport: _WrappedTransport | None = None) → None

Transmit a packet from the event loop.

async async_unregister_all_services() → None

Send goodbye packets for every registered service and drop them all.

Runs only at shutdown, so unlike the single service calls it returns nothing to await separately.

async async_unregister_service(info: ServiceInfo) → Awaitable

Withdraw a service from the event loop, broadcasting goodbyes.

async async_update_interfaces(interfaces: Sequence[str | int | tuple[tuple[str, int, int], int]] | InterfaceChoice | None = None, ip_version: IPVersion | None = None, apple_p2p: bool | None = None) → None

Rescan network interfaces and reconcile the sockets in use.

Adds sockets for interfaces that appeared, drops sockets for interfaces that disappeared, and re-announces existing registrations when a new sender appeared. interfaces, ip_version and apple_p2p each default to the value passed at construction; pass a new value to switch it. When the resulting interface set is unchanged this is a no-op (no sockets touched, nothing re-announced). The listen socket is rebuilt if the new set needs a different address family; unicast mode is fixed at construction. Concurrent calls are serialized. Bringing up interfaces is best-effort: a requested interface that fails to bind, or fails to re-join after a rebuild, is logged rather than raised, and likewise a registration that fails to re-announce is logged so one failure cannot block the others. Raises RuntimeError if apple_p2p is set on a non-Apple platform (input validation, matching the constructor).

async async_update_service(info: ServiceInfo) → Awaitable

Publish updated records for an already registered service.

Returns an awaitable that completes once the rebroadcasts finish.

async async_wait(timeout: float) → None

Pause until notified or until timeout milliseconds pass.

async async_wait_for_start(timeout: float = 9) → None

Wait for start up for actions that require a running Zeroconf instance.

Throws NotRunningException if the instance is not running or could not be started.

close() → None

Shut down the sockets and engine for good; safe to call repeatedly.

generate_service_broadcast(info: ServiceInfo, ttl: int | None, broadcast_addresses: bool = True) → DNSOutgoing

Generate a broadcast to announce a service.

generate_service_query(info: ServiceInfo) → DNSOutgoing

Generate a query to lookup a service.

generate_unregister_all_services() → DNSOutgoing | None

Generate a DNSOutgoing goodbye for all services and remove them from the registry.

get_service_info(type_: str, name: str, timeout: int = 3000, question_type: DNSQuestionType | None = None) → ServiceInfo | None

Look up details for a service on the network.

Queries for the given fully qualified type and name, waiting up to timeout milliseconds, and returns a populated ServiceInfo or None when nothing answered in time. question_type forces QM or QU questions instead of the automatic choice.

notify_all() → None

Wake every waiter and fire the listeners, from any thread.

register_service(info: ServiceInfo, ttl: int | None = None, allow_name_change: bool = False, cooperating_responders: bool = False, strict: bool = True) → None

Announce a service on the network.

Probes for conflicts first; with allow_name_change the instance name is renamed until it is unique. May raise EventLoopBlocked when the event loop cannot complete the registration in time.

remove_all_service_listeners() → None

Stop the browsers behind every registered listener.

remove_listener(listener: RecordUpdateListener) → None

Detach a record listener from any thread.

remove_service_listener(listener: ServiceListener) → None

Stop the browser behind the given listener.

send(out: DNSOutgoing, addr: str | None = None, port: int = 5353, v6_flow_scope: tuple[()] | tuple[int, int] = (), transport: _WrappedTransport | None = None) → None

Queue a packet for transmission from any thread.

start() → None

Start Zeroconf.

property started: bool

Check if the instance has started.

unregister_all_services() → None

Send goodbye packets for every registered service and drop them all.

May raise EventLoopBlocked when the event loop cannot finish the shutdown broadcasts in time.

unregister_service(info: ServiceInfo) → None

Withdraw a service by broadcasting goodbye records.

May raise EventLoopBlocked when the event loop cannot finish the withdrawal in time.

update_interfaces(interfaces: Sequence[str | int | tuple[tuple[str, int, int], int]] | InterfaceChoice | None = None, ip_version: IPVersion | None = None, apple_p2p: bool | None = None) → None

Rescan network interfaces and reconcile the sockets in use.

While it is not expected during normal operation, this function may raise EventLoopBlocked if the underlying call to async_update_interfaces cannot be completed. Raises RuntimeError if apple_p2p is set on a non-Apple platform.

update_service(info: ServiceInfo) → None

Publish updated records for an already registered service.

May raise EventLoopBlocked when the event loop cannot complete the update in time.

class zeroconf.ZeroconfServiceTypes

Bases: ServiceListener

Return all of the advertised services on any local networks

add_service(zc: Zeroconf, type_: str, name: str) → None

Service added.

classmethod find(zc: Zeroconf | None = None, timeout: int | float = 5, interfaces: Sequence[str | int | tuple[tuple[str, int, int], int]] | InterfaceChoice = InterfaceChoice.All, ip_version: IPVersion | None = None) → tuple[str, ...]

Return all of the advertised services on any local networks.

Parameters:

• zc – Zeroconf() instance. Pass in if already have an instance running or if non-default interfaces are needed

• timeout – seconds to wait for any responses

• interfaces – interfaces to listen on.

• ip_version – IP protocol version to use.

Returns:

tuple of service type strings

remove_service(zc: Zeroconf, type_: str, name: str) → None

Service removed.

update_service(zc: Zeroconf, type_: str, name: str) → None

Service updated.

zeroconf.current_time_millis() → float

Monotonic clock reading in milliseconds.

Must stay aligned with asyncio.loop.time(); the backing clock is an implementation detail and may change.

A pure python implementation of multicast DNS service discovery.

Licensed under LGPL-2.1-or-later; see COPYING for details. This file is part of a continuously modified work; modification dates are recorded in the project’s git history.

class zeroconf.asyncio.AsyncServiceBrowser(zeroconf: Zeroconf, type_: str | list, handlers: ServiceListener | list[Callable[[...], None]] | None = None, listener: ServiceListener | None = None, addr: str | None = None, port: int = 5353, delay: int = 10000, question_type: DNSQuestionType | None = None)

Bases: _ServiceBrowserBase

Event loop browser that fires ServiceListener callbacks as services of the requested types appear, change, and disappear.

async async_cancel() → None

Cancel the browser.

done

query_scheduler

types: set[str]

zc

class zeroconf.asyncio.AsyncServiceInfo(type_: str, name: str, port: int | None = None, weight: int = 0, priority: int = 0, properties: bytes | dict | None = None, server: str | None = None, host_ttl: int = 120, other_ttl: int = 4500, *, addresses: Sequence[bytes | str] | None = None, parsed_addresses: list[str] | None = None, interface_index: int | None = None)

Bases: ServiceInfo

An async version of ServiceInfo.

host_ttl

interface_index

key

other_ttl

port

priority

server

server_key

text

type

weight

class zeroconf.asyncio.AsyncZeroconf(interfaces: Sequence[str | int | tuple[tuple[str, int, int], int]] | InterfaceChoice = InterfaceChoice.All, unicast: bool = False, ip_version: IPVersion | None = None, apple_p2p: bool = False, zc: Zeroconf | None = None)

Bases: object

Awaitable facade over Zeroconf for registration, browsing, and resolution; expects a running asyncio event loop.

async async_add_service_listener(type_: str, listener: ServiceListener) → None

Browse a service type, delivering events to the listener.

Replaces any browser previously registered for the same listener.

async async_close() → None

Unregister everything and shut the wrapped Zeroconf down.

async async_get_service_info(type_: str, name: str, timeout: int = 3000, question_type: DNSQuestionType | None = None) → AsyncServiceInfo | None

Look up details for a service on the network.

Queries for the given fully qualified type and name, waiting up to timeout milliseconds, and returns a populated AsyncServiceInfo or None when nothing answered in time. question_type forces QM or QU questions instead of the automatic choice.

async async_register_service(info: ServiceInfo, ttl: int | None = None, allow_name_change: bool = False, cooperating_responders: bool = False, strict: bool = True) → Awaitable

Announce a service on the network.

Returns an awaitable that completes once the announcements have been sent.

async async_remove_all_service_listeners() → None

Stop and drop every browser started through add_service_listener.

async async_remove_service_listener(listener: ServiceListener) → None

Stop and drop the browser registered for the listener, if any.

async async_unregister_all_services() → None

Send goodbye packets for every registered service and drop them all.

Runs only at shutdown, so unlike the single service calls it returns nothing to await separately.

async async_unregister_service(info: ServiceInfo) → Awaitable

Withdraw a service, returning an awaitable that completes once the goodbyes are sent.

async async_update_interfaces(interfaces: Sequence[str | int | tuple[tuple[str, int, int], int]] | InterfaceChoice | None = None, ip_version: IPVersion | None = None, apple_p2p: bool | None = None) → None

Rescan network interfaces and reconcile the sockets in use.

Adds sockets for interfaces that appeared, drops sockets for interfaces that disappeared, and re-announces existing registrations on the resulting senders. interfaces, ip_version and apple_p2p each default to the construction-time value. Raises RuntimeError if apple_p2p is set on a non-Apple platform.

async async_update_service(info: ServiceInfo) → Awaitable

Publish updated records for an already registered service.

Returns an awaitable that completes once the rebroadcasts finish.

class zeroconf.asyncio.AsyncZeroconfServiceTypes

Bases: ZeroconfServiceTypes

An async version of ZeroconfServiceTypes.

async classmethod async_find(aiozc: AsyncZeroconf | None = None, timeout: int | float = 5, interfaces: Sequence[str | int | tuple[tuple[str, int, int], int]] | InterfaceChoice = InterfaceChoice.All, ip_version: IPVersion | None = None) → tuple[str, ...]

Return all of the advertised services on any local networks.

Parameters:

• aiozc – AsyncZeroconf() instance. Pass in if already have an instance running or if non-default interfaces are needed

• timeout – seconds to wait for any responses

• interfaces – interfaces to listen on.

• ip_version – IP protocol version to use.

Returns:

tuple of service type strings