Usage

getmac provides a Python function, get_mac_address(), and a command-line interface, getmac. The command-line interface is documented in Command-Line Interface. This page documents usage from Python as a library.

If a MAC address was found, get_mac_address() will return a lowercase colon-separated MAC address as a string. If no MAC was found, or an exception occurred, None is returned.

Examples

Basic example:

Python 3.11.4 (tags/v3.11.4:d2340ef, Jun  7 2023, 05:45:37) [MSC v.1934 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
Ctrl click to launch VS Code Native REPL
>>> from getmac import get_mac_address
>>> get_mac_address(ip='192.168.0.1')
'00:11:22:33:44:55'

Interface names

from getmac import get_mac_address

# Linux example
get_mac_address(interface="eth0")

# Windows example
get_mac_address(interface="Ethernet 3")

IP addresses and hostnames

from getmac import get_mac_address

# IPv4 example
get_mac_address(ip="192.168.0.1")

# IPv6 example
get_mac_address(ip6="::1")

# Hostname example
get_mac_address(hostname="localhost")

Updated ARP/NDP table before lookup

Update the ARP table (IPv4) or NDP list (IPv6) before looking up the MAC. This results in a UDP packet being sent to the target IP address on port 55555 (by default).

from getmac import get_mac_address

get_mac_address(ip="10.0.0.1", network_request=True)

The host’s entry is only added to the table once it replies, which can take longer than getmac takes to check the table. To keep checking for it for up to a number of seconds, set ARP_TIMEOUT (--arp-timeout on the command line):

from getmac import get_mac_address, settings

settings.ARP_TIMEOUT = 1.0  # Default is 0, check once
get_mac_address(ip="10.0.0.1")

Changing settings

Available settings are documented in Configuration. Here’s an example of changing some settings at runtime:

from getmac import get_mac_address, settings

# Enable debugging
settings.DEBUG = 2  # DEBUG level 2
print(get_mac_address(interface="Ethernet 3"))

# Change the UDP port used for updating the ARP table (UDP packet)
settings.PORT = 55555  # Default port for getmac is 55555
print(get_mac_address(ip="192.168.0.1", network_request=True))

Using ipaddress objects

You can also use the standard library’s ipaddress module to specify IP addresses. This works for both IPv4 and IPv6 addresses. The ip argument also accepts IPv6Address and IPv6Interface objects, and will treat them as IPv6 addresses. The ip6 argument is not needed when using these objects, but can be used if desired.

from getmac import get_mac_address
from ipaddress import ip_address, IPv4Interface, IPv6Interface

ipv4_addr = ip_address("192.168.0.1")
print(get_mac_address(ip=ipv4_addr))

ipv6_addr = ip_address("::1")
print(get_mac_address(ip=ipv6_addr))

ipv4_iface = IPv4Interface("192.168.0.1/24")
print(get_mac_address(ip=ipv4_iface))

ipv6_iface = IPv6Interface("::1/128")
print(get_mac_address(ip=ipv6_iface))

Default interface name

Get the name of the system’s default network interface using get_default_interface(). This leverages the same logic that getmac uses internally to determine the default interface (e.g. for when get_mac_address() is called without any arguments).

from getmac import get_default_interface
print(get_default_interface())

Configuration

Settings that affect the behavior of getmac are in the variables module, with the exception of the logging settings, which are handled by Python’s logging module. The following settings are available:

  • logging.getLogger("getmac"): Runtime messages and errors are recorded to the getmac logger using Python’s logging module. They can be configured by using logging.basicConfig() or adding logging.Handler instances to the getmac logger.

  • DEBUG: integer value that controls debugging output. The higher the value, the more output you get.

  • PORT: the UDP port used to populate the ARP table (IPv4) or NDP list (IPv6) when looking up MACs for hosts or IPs (see the documentation of the network_request argument in get_mac_address() for details).

  • ARP_TIMEOUT: how long to keep checking the ARP table (IPv4) or NDP list (IPv6) for a host after sending the UDP packet, in seconds. 0 (the default) checks once, without waiting.

  • COMMAND_TIMEOUT: how long to wait for a command that getmac runs (such as arp or ipconfig.exe) to finish, in seconds. A command that takes longer is stopped, and the next method is tried. The default is 15 seconds, and None or 0 waits for as long as the command takes.

  • OVERRIDE_PLATFORM: Override the platform detection with the given value (e.g. "linux", "windows", "freebsd", etc). Any values returned by platform.system() are valid.

  • FORCE_METHOD: Name of method to use. This will force a specific method to be used, e.g. getmac.getmac.IpNeighborShow with the string "IpNeighborShow". This will be used regardless of the method’s type or platform compatibility, and test() will NOT be checked! The list of available methods is in getmac.getmac.METHODS.

Notes

  • "localhost" or "127.0.0.1" will always return "00:00:00:00:00:00", as this is the MAC address of the loopback interface.

  • If none of the arguments are selected, the default network interface for the system will be used. If the default network interface cannot be determined (for example, if there aren’t any routes) or doesn’t have a MAC (for example, a VPN tunnel), then the first interface that has a MAC and isn’t a loopback interface is used. If there isn’t one, None is returned. On Windows, only the default interface is used.

  • The first four arguments to get_mac_address() are mutually exclusive. network_request does not have any functionality when the interface argument is specified, and can be safely set if using in a script.

  • Most Exceptions will be handled silently and returned as a None. If you run into problems, you can set DEBUG to true and get more information about what’s happening. If you’re still having issues, please create an issue on GitHub and include the output with DEBUG enabled. As of version 1.0.0, a RuntimeError is raised in cases where no possible methods are found matching the type of request and platform or all methods found fail to test (in other words, don’t work).

Limitations & Known Issues

  • The physical transport is assumed to be Ethernet (802.3). Others, such as Wi-Fi (802.11), are currently not tested or considered. I plan to address this in the future, and am definitely open to pull requests or issues related to this, including error reports.

  • “Remote hosts” refer to hosts in your local layer 2 network, also known as a “broadcast domain”, “LAN”, or “VLAN”. As far as I know, there is not a reliable method to get a MAC address for a remote host external to the LAN. If you know any methods otherwise, please open an issue on GitHub or shoot me an email, I’d love to be wrong about this.

  • Some methods may not work on certain platforms or configurations. If a method fails, getmac will try the next available method until it finds one that works or exhausts all options.

  • The accuracy and reliability of the MAC address retrieval may vary depending on the network configuration, the target host’s settings, and other factors. Please refer to the documentation of each method for more details on their behavior and limitations.

  • Depending on the platform, there could be a performance detriment, due to heavy usage of regular expressions.

  • Platform test coverage is imperfect. If you’re having issues, then you might be using a platform I haven’t been able to test. Keep calm, open a GitHub issue, and I’d be more than happy to help.

  • Linux, WSL: Getting the mac of a local interface IP does not currently work (getmac --ip 10.0.0.4 will fail if 10.0.0.4 is the IP address of a local interface). This issue may be present on other POSIX systems as well.

  • Hostnames for IPv6 devices are not yet supported.

  • Android: newer versions of Android don’t have many of the commands getmac uses, and restrict access to network information, so getmac may not find anything. Installing BusyBox or the Termux iproute2 and net-tools packages adds the missing commands, but they can still be blocked by Android’s restrictions.

  • Windows: ipconfig.exe (a fallback for when getmac.exe doesn’t work) only finds interfaces by name in English output, since the adapter headers are translated.

  • IPv6 support is good but lags behind IPv4 in some places and isn’t as well-tested across the supported platform set.