get_mac_address

getmac.get_mac_address(interface=None, ip=None, ip6=None, hostname=None, network_request=True)[source]

Get a MAC address from a local interface or remote host.

Only ONE of the first four arguments may be used: interface, ip, ip6, or hostname. If none of the arguments are selected, the default network interface for the system will be used. If it can’t be found or doesn’t have a MAC, the first interface that has a MAC and isn’t a loopback interface is used (except on Windows).

The MAC is usually a unicast IEEE 802 MAC-48 address.

Note

hostname="localhost" and ip="127.0.0.1" always return "00:00:00:00:00:00". Other spellings, such as ::1, 127.0.0.2, LOCALHOST, or the host’s own name, aren’t short-circuited like this, and return None.

Note

It is assumed that the host is using Ethernet or Wi-Fi. While other protocols such as Bluetooth may work, this has not been tested and should not be relied upon. If this functionality is needed, please open an issue or PR.

Note

Exceptions raised by methods are caught and logged, and the next method is tried. The exception is a method forced with FORCE_METHOD, whose exceptions are not caught.

Parameters:

  • interface (Union[str, bytes, None]) – Name of a local network interface (e.g “Ethernet 3”, “eth0”, “ens32”)

  • ip (Union[str, bytes, IPv4Address, IPv4Interface, IPv6Address, IPv6Interface, None]) – Canonical dotted decimal IPv4 address of a remote host (e.g 192.168.0.1), or a ipaddress object (IPv4Address or IPv4Interface). This will also accept IPv6Address and IPv6Interface, and treat them as if ip6 argument was set instead.

  • ip6 (Union[str, bytes, IPv6Address, IPv6Interface, None]) – Canonical shortened IPv6 address of a remote host (e.g fe80::1), or a ipaddress object (IPv6Address or IPv6Interface). A link-local address can have a zone (fe80::1%en0, or fe80::1%2 with the interface’s index), which macOS, the BSDs, Solaris, and illumos use. On Linux and Windows, pass the address without one.

  • hostname (Union[str, bytes, None]) – DNS hostname of a remote host (e.g “router1.mycorp.com”, “localhost”)

  • network_request (bool) – If network requests should be made when attempting to find the MAC of a remote host. It does nothing for interface. For ip, ip6 and hostname, getmac tries to get the host into the ARP/NDP table first: it sends an ARP request (IPv4 only, with SendARP on Windows or arping if it’s installed), or else an empty UDP packet to the host. The port for the packet is getmac.variables.Settings.PORT (by default, 55555). To wait for the host to reply to it, set getmac.variables.Settings.ARP_TIMEOUT. With no arguments on Windows, it also connects a UDP socket to 1.1.1.1:53 (nothing is sent) to find the default interface’s IP. If this is False, methods that send network requests (such as arping) aren’t used. See the exact sequence.

Return type:

Optional[str]

Returns:

Lowercase colon-separated MAC address. If no MAC was found, or a method raised an exception, None is returned. The exception is a method forced with FORCE_METHOD, whose exceptions are raised.

Raises:

  • RuntimeError – If no valid methods are found for the type of MAC requested, or another critical error occurs (potentially due to a bug in getmac).

  • ValueError – If ip or ip6 is an ipaddress network (getmac needs a host, not a network), or if an argument is an unsupported type.

Warns:

RuntimeWarning – If there are no methods for the platform and getmac falls back to the generic other methods. This is an exception if warnings are errors (e.g. python -W error::RuntimeWarning).