Skip to main content

Get MAC addresses of remote hosts and local interfaces

Project description

Latest version on PyPI Travis CI build status Appveyor build status PyPI - Downloads PyPI downloads of the old name

Pure-Python package to get the MAC address of network interfaces and hosts on the local network.

It provides a platform-independant interface to get the MAC addresses of:

  • System network interfaces (by interface name)
  • Remote hosts on the local network (by IPv4/IPv6 address or hostname)

It provides one function: get_mac_address()

asciicast

asciicast

Should you use this package?

If you only need the addresses of network interfaces, have a limited set of platforms to support, and are able to handle C-extension modules, then you should instead check out the excellent netifaces package by Alastair Houghton. It is significantly faster, well-maintained, and has been around much longer than this has. Another great option that fits these requirements is the well-known and battle-hardened psutil package by Giampaolo Rodola.

If the only system you need to run on is Linux, you can run as root, and C-extensions modules are fine, then you should instead check out the arpreq package by Sebastian Schrader. It can be significantly faster, especially in the case of hosts that don't exist (at least currently).

If you want to use psutil, scapy, or netifaces, I have examples of how to do so in a GitHub Gist.

Installation

Stable release from PyPI:

pip install getmac

Latest development version:

pip install https://github.com/ghostofgoes/getmac/archive/master.tar.gz

Python examples

from getmac import get_mac_address
eth_mac = get_mac_address(interface="eth0")
win_mac = get_mac_address(interface="Ethernet 3")
ip_mac = get_mac_address(ip="192.168.0.1")
ip6_mac = get_mac_address(ip6="::1")
host_mac = get_mac_address(hostname="localhost")
updated_mac = get_mac_address(ip="10.0.0.1", network_request=True)

# Enabling debugging
from getmac import getmac
getmac.DEBUG = 2  # DEBUG level 2
print(getmac.get_mac_address(interface="Ethernet 3"))

# Changing the port used for updating ARP table (UDP packet)
from getmac import getmac
getmac.PORT = 44444  # Default: 55555
print(get_mac_address(ip="192.168.0.1", network_request=True))

Terminal examples

Python 2 users: use getmac2 or python -m getmac instead of getmac.

getmac --help
getmac --version

# No arguments will return MAC of the default interface.
getmac
python -m getmac

# Interface names, IPv4/IPv6 addresses, or Hostnames can be specified
getmac --interface ens33
getmac --ip 192.168.0.1
getmac --ip6 ::1
getmac --hostname home.router

# Running as a Python module with shorthands for the arguments
python -m getmac -i 'Ethernet 4'
python -m getmac -4 192.168.0.1
python -m getmac -6 ::1
python -m getmac -n home.router

# Getting the MAC address of a remote host requires the ARP table to be populated.
# By default, getmac will populate the table by sending a small UDP packet to a high port of the host (by default, 55555).
# This can be disabled with --no-network-request, as shown here:
getmac --no-network-request -4 192.168.0.1
python -m getmac --no-network-request -n home.router

# Debug levels can be specified with '-d'
getmac --debug
python -m getmac -d -i enp11s4
python -m getmac -dd -n home.router

Function: get_mac_address()

  • interface: Name of a network interface on the system.
  • ip: IPv4 address of a remote host.
  • ip6: IPv6 address of a remote host.
  • hostname: Hostname of a remote host.
  • network_request: If an network request should be made to update and populate the ARP/NDP table of remote hosts used to lookup MACs in most circumstances. Disable this if you want to just use what's already in the table, or if you have requirements to prevent network traffic. The network request is a empty UDP packet sent to a high port, 55555 by default. This can be changed by setting getmac.PORT to the desired integer value. Additionally, on Windows, this will send a UDP packet to 1.1.1.1:53 to attempt to determine the default interface.

Features

  • Pure-Python (no compiled C-extensions required!)
  • Python 2.7 and 3.4+
  • Lightweight, with no dependencies and a small package size
  • Can be dropped into a project as a standalone .py file
  • Supports most interpreters: CPython, pypy, pypy3, IronPython, and Jython
  • Provides a simple command line tool (when installed as a package)
  • MIT licensed!

Legacy Python versions

If you are running a old Python (2.6/3.3 and older), then you can install an older version of getmac that supported that version. You can get the wheels in the GitHub releases, or from PyPI with a current version of pip and some special arguments.

  • Python 2.5: get-mac 0.5.0
  • Python 2.6: getmac 0.6.0
  • Python 3.2: get-mac 0.3.0
  • Python 3.3: get-mac 0.3.0

NOTE: these versions do not have many of the performance improvements, platform support, and bug fixes that came with later releases. They generally work, just not as well. However, if you're using such an old Python, you probably don't care about all that :)

Notes

  • If none of the arguments are selected, the default network interface for the system will be used.
  • "Remote hosts" refer to hosts in your local layer 2 network, also commonly referred to 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 a GitHub issue or shoot me an email, I'd love to be wrong about this.
  • The first four arguments 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.
  • The physical transport is assumed to be Ethernet (802.3). Others, such as Wi-Fi (802.11), are currently not tested or considored. I plan to address this in the future, and am definitely open to pull requests or issues related to this, including error reports.
  • 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.
  • Messages are output using the warnings module, and print() if getmac.DEBUG enabled (any value greater than 0). If you are using logging, they can be captured using logging.captureWarnings(). Otherwise, they can be suppressed using warnings.filterwarnings("ignore"). https://docs.python.org/3/library/warnings.html

Commands and techniques by platform

  • Windows
    • Commands: getmac, ipconfig
    • Libraries: uuid, ctypes
  • Linux/Unix
    • Commands: arp, ip, ifconfig, netstat, ip link
    • Libraries: uuid, fcntl
    • Files: /sys/class/net/{iface}/address, /proc/net/arp
    • Default interfaces: /proc/net/route, route, ip route list
  • Mac OSX (Darwin)
    • networksetup
    • Same commands as Linux
  • WSL: Windows commands are used for remote hosts, and Unix commands are used for interfaces

Platforms currently supported

All or almost all features should work on "supported" platforms.

  • Windows
    • Desktop: 7, 8, 8.1, 10
    • Server: TBD
    • Partially supported and untested: 2000, XP, Vista
  • Linux distros
    • CentOS/RHEL 6+ (Only with Python 2.7+)
    • Ubuntu 16.04+ (14.04 and older should work, but are untested)
    • Fedora
  • Mac OSX (Darwin)
    • The latest two versions probably (TBD)
  • Windows Subsystem for Linux (WSL)
  • Docker

Docker

docker build -f packaging/Dockerfile -t getmac .
docker run -it getmac:latest --help
docker run -it getmac:latest --version
docker run -it getmac:latest -n localhost

Caveats & Known issues

Please report any problems by opening a issue on GitHub!

Caveats

  • 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.

Known Issues

  • Hostnames for IPv6 devices are not yet supported.
  • Windows: the "default" of selecting the default route interface only works effectively if network_request is enabled. Otherwise, Ethernet as the default.

Name change

The package name changed to getmac from get-mac in Fall 2018. This affected the package name, the CLI script, and some of the documentation. There were no changes to the core library code. If you or a package you are using is still using the old name, please update it's dependencies to use the new name. Likely places are a requirements.txt file, the install_requires argument to setup() in setup.py, or a Pipfile. The old package will no receive any further updates, and will eventually be removed from PyPI entirely (likely around when 1.0.0 is released).

Deathwatch for the old name: Downloads of the old name

Background and history

The Python standard library has a robust set of networking functionality, such as urllib, ipaddress, ftplib, telnetlib, ssl, and more. Imagine my surprise, then, when I discovered there was not a way to get a seemingly simple piece of information: a MAC address. This package was born out of a need to get the MAC address of hosts on the network without needing admin permissions, and a cross-platform way get the addresses of local interfaces.

Contributing

Contributors are more than welcome! See the contribution guide to get started, and checkout the todo list for a full list of tasks and bugs.

Before submitting a PR, please make sure you've completed the pull request checklist!

The Python Discord server is a good place to ask questions or discuss the project (Handle: @KnownError).

Contributors

  • Christopher Goes (@ghostofgoes) - Author and maintainer
  • Calvin Tran (@cyberhobbes) - Windows interface detection improvements
  • Izra Faturrahman (@Frizz925) - Unit tests using the platform samples
  • Jose Gonzalez (@Komish) - Docker container and Docker testing
  • @fortunate-man - Awesome usage videos
  • @martmists - legacy Python compatibility improvements
  • @hargoniX - scripts and specfiles for RPM packaging

Sources

Many of the methods used to acquire an address and the core logic framework are attributed to the CPython project's UUID implementation.

Other notable sources

License

MIT. Feel free to copy, modify, and use to your heart's content. Enjoy :)

Changelog

NOTE: if any changes significantly impact your project or use case, please open an issue on GitHub or send me an email (see git commit author info for address).

UNRELEASED (xx/xx/2019)

0.7.0 (01/27/2019)

Added

  • Type annotations (PEP 484)

Removed

  • Dropped support for Python 2.6
  • Removed the usage of third-party packages (netifaces, psutil, scapy, and arpreq). This should improve the performance of lookups of non-existant interfaces or hosts, since feature was punishing that path without providing much value. If you want to use these packages directly, I have a guide on how to do so on a GitHub Gist.

Changed

  • Significantly improved the performance of the common cases on Linux for interfaces and remote hosts
  • Improved POSIX interface performance. Commands specific to OSX will be run only on that platform, and vice-versa.
  • Significantly improved the speed and accuracy of determining the default interface on Linux
  • Python 2 will install an executor named getmac2 and Python 3 an executor named getmac so they don't conflict when both RPMs are installed on the same system (Credit: @hargoniX)
  • The warnings module will only be imported if a error/warning occurs (improve compatibility with some freezers, notably PyInstaller)
  • Improved system platform detection
  • Various other minor performance improvements

Development

  • Added unit tests for the samples (Credit: @Frizz925)
  • Scripts for building RPMs in the /scripts directory (Credit: @hargoniX)
  • Improved code quality and health checks
  • Include the CHANGELOG on the PyPI project page
  • Using pytest for all tests now instead of unittest

Documentation

  • Added instructions on how to build a Debian package (Credit: @kofrezo)

0.6.0 (10/06/2018)

Added

  • Windows default interface detection if network_request is enabled (Credit: @cyberhobbes)
  • Docker container (Credit: @Komish)

Changed

  • Changed name to getmac. This applies to everything, including command line tool, PyPI, GitHub, and the documentation. This is a breaking change, but needed to happen to remove a huge amount of ambiguity that was causing issues with packaging, documentation, and several other efforts, not to mention my sanity. Long-term, the only downside is a conflict on Windows CLI with getmac.exe.
  • Use proper Python 2-compatible print functions (Credit: @martmists)

Removed

  • Support for Python 2.5. It is not feasible to test, and potentially breaks some useful language features, such as __future__
  • Variables PORT and DEBUG from top-level package imports, since changing them would have no actual effect on execution. Instead, use getmac.getmac.DEBUG.

Dev

  • Added example videos demonstrating usage (Credit: @fortunate-man)
  • Added contribution guide
  • Added documentation on ReadTheDocs
  • Added a manpage

0.5.0 (09/24/2018)

Added

  • Full support for Windows Subsystem for Linux (WSL). This is working for all features, including default interface selection! The only edge case is lookup of remote host IP addresses that are actually local interfaces won't resolve to a MAC (which should be ff-ff-ff-ff-ff-ff).

Changed

  • Require argparse if Python version is 2.6 or older

Dev

  • Updated tox tests: added Jython and IronPython, removed 2.6

0.4.0 (09/21/2018)

Added

  • New methods for remote host MACs
    • Windows: arp
    • POSIX: arpreq package
  • New methods for interface MACs
    • Windows: wmic nic
  • DEBUG levels: DEBUG value is now an integer, and increasing it will increase the amount and verbosity of output. On the CLI, it can be configured by increasing the amount of characters for the debug argument, e.g. '-dd' for DEBUG level 2.
  • Jython support (Note: on Windows Jython currently only works with interfaces)
  • IronPython support

Changed

  • Significant performance improvement for remote hosts. Previously, the average for get_mac_address(ip='10.0.0.100') was 1.71 seconds. Now, the average is 12.7 miliseconds, with the special case of a unpopulated arp table being only slightly higher. This was brought about by changes in how the arp table is populated. The original method was to use the host's ping command to send an ICMP packet to the host. This took time, which heavily delayed the ability to actually get an address. The solution is to instead simply send a empty UDP packet to a high port. The port this packet is sent to can be configured using the module variable getmac.PORT.
  • "Fixed" resolution of localhost/127.0.0.1 by hardcoding the response. This should resolve a lot of problematic edge cases. I'm ok with this for now since I don't know of a case when it isn't all zeroes.
  • Greatly increased the reliability of getting host and interface MACs on Windows
  • Improved debugging output
  • Tightened up the size of getmac.py
  • Various minor stability and performance improvements
  • Add LICENSE to PyPI package

Removed

  • Support for Python 3.2 and 3.3. The total downloads from PyPI with those versions in August was ~53k and ~407K, respectfully. The majority of those are likely from automated testing (e.g. TravisCI) and not actual users. Therefore, I've decided to drop support to simplify development, especially since before 3.4 the 3.x series was still very much a "work in progress".

Dev

  • Added automated tests for Windows using Appveyor
  • Tox runner for tests
  • Added github.io page
  • Improved TravisCI testing

0.3.0 (08/30/2018)

Added

  • Attempt to use Python modules if they're installed. This is useful for larger projects that already have them installed as dependencies, as they provide a more reliable means of getting information.
    • psutil: Interface MACs on all platforms
    • scapy: Interface MACs and Remote MACs on all platforms
    • netifaces: Interface MACs on Non-Windows platforms
  • New methods for remote MACs
    • POSIX: ip neighbor show, Abuse of uuid._arp_getnode()
  • New methods for Interface MACs
    • POSIX: lanscan -ai (HP-UX)

Changed

  • Certain critical failures that should never happen will now warn instead of failing silently.
  • Added a sanity check to the ip6 argument (IPv6 addresses)
  • Improved performance in some areas
  • Improved debugging output

Fixed

  • Major Bugfix: search of proc/net/arp would return shorter addresses in the same subnet if they came earlier in the sequence. Example: a search for 192.168.16.2 on Linux would instead return the MAC address of 192.168.16.254 with no errors or warning whatsoever.
  • Significantly improved default interface detection. Default interfaces are now properly detected on Linux and most other POSIX platforms with ip or route commands available, or the netifaces Python module.

Dev

  • Makefile
  • Vagrantfile to spin up testing VMs for various platforms using Vagrant
  • Added more samples of command output on platforms (Ubuntu 18.04 LTS)

0.2.4 (08/26/2018)

Fixed

  • Fixed identification of remote host on OSX
  • Resolved hangs and noticeable lag that occurred when "network_request" was True (the default)

0.2.3 (08/07/2018)

Fixed

  • Remote host for Python 3 on Windows

0.2.2

Added

  • Short versions of CLI arguments (e.g. "-i" for "--interface")

Changed

  • Improved usage of "ping" across platforms and IP versions
  • Various minor tweaks for performance
  • Improved Windows detection

Fixed

  • Use of ping command with hostname

Dev:

  • Improvements to internal code

0.2.1

Nothing changed. PyPI just won't let me push changes without a new version.

0.2.0 (04/15/2018)

Added

  • Checks for default interface on Linux systems
  • New methods of hunting for addresses on Windows, Mac OS X, and Linux

Changed

  • CLI will output nothing if it failed, instead of "None"
  • CLI will return with 1 on failure, 0 on success
  • No CLI arguments now implies the default host network interface
  • Added an argumnent for debugging: --debug
  • Removed -d option from --no-network-requests

Fixed

  • Interfaces on Windows and Linux (including Bash for Windows)
  • Many bugs

Removed

  • Support for Python 2.6 on the CLI

Dev

  • Overhaul of internals

0.1.0 (04/15/2018):

Added

  • Addition of a terminal command: get-mac
  • Ability to run as a module from the command line: python -m getmac

Changed

  • arp_request argument was renamed to network_request
  • Updated docstring
  • Slight reduction in the size of getmac.py

Dev

  • Overhauled the README
  • Moved tests into their own folder
  • Added Python 3.7 to list of supported snakes

0.0.4 (11/12/2017):

  • Python 2.6 compatibility

0.0.3 (11/11/2017):

  • Fixed some addresses returning without colons
  • Added more rigorous checks on addresses before returning them

0.0.2 (11/11/2017):

  • Remove print statements and other debugging output

0.0.1 (10/23/2017):

  • Initial pre-alpha

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

getmac-0.7.0.tar.gz (34.5 kB view hashes)

Uploaded Source

Built Distribution

getmac-0.7.0-py2.py3-none-any.whl (22.7 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page