{"id":9092,"library":"macaddress","title":"MAC Address Library","description":"A module for handling hardware identifiers like MAC addresses, EUI-48, EUI-64, and OUI. Heavily inspired by Python's built-in `ipaddress` module, `macaddress` provides classes to check if a string represents a valid hardware address, convert between various string and binary forms, and allows users to define custom hardware address types. It adheres to the SemVer 2.0.0 specification, with the current stable version being 2.0.2.","status":"active","version":"2.0.2","language":"en","source_language":"en","source_url":"https://github.com/mentalisttraceur/python-macaddress","tags":["networking","mac address","hardware identifiers","eui48","eui64","oui"],"install":[{"cmd":"pip install macaddress","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"Primary import for the library's functionality.","symbol":"macaddress","correct":"import macaddress"},{"note":"Used for representing EUI-48 MAC addresses (also aliased as MAC).","symbol":"EUI48","correct":"from macaddress import EUI48"},{"note":"Used for representing EUI-64 addresses.","symbol":"EUI64","correct":"from macaddress import EUI64"},{"note":"Used for representing Organizationally Unique Identifiers.","symbol":"OUI","correct":"from macaddress import OUI"},{"note":"Base class for defining custom hardware address types.","symbol":"HWAddress","correct":"from macaddress import HWAddress"}],"quickstart":{"code":"import macaddress\n\n# Create an EUI48 (MAC) address object\nmac = macaddress.EUI48('01-23-45-67-89-ab')\nprint(f\"MAC Address: {mac}\")\n\n# Access different formats\nprint(f\"MAC in colon format: {mac.colon}\")\nprint(f\"MAC in period format: {mac.period}\")\nprint(f\"MAC as bytes: {mac.packed}\")\n\n# Validate an address string\ntry:\n    invalid_mac = macaddress.EUI48('foo bar')\nexcept ValueError as e:\n    print(f\"Error parsing invalid MAC: {e}\")\n\n# Create an EUI64 address\neui64 = macaddress.EUI64('01-23-45-67-89-ab-cd-ef')\nprint(f\"EUI64 Address: {eui64}\")\n\n# Define a custom format (example from docs)\nclass CustomMAC(macaddress.MAC):\n    formats = macaddress.MAC.formats + (\n        'xx-xx-xx-xx-xx-xx-xx-xx-xx-xx-xx-xx-xx-xx-xx-xx-xx-xx-xx-xx',\n    )\n\ncustom_mac = CustomMAC('01-23-45-67-89-AB-01-23-45-67-89-AB-01-23-45-67-89-AB')\nprint(f\"Custom MAC: {custom_mac}\")","lang":"python","description":"This quickstart demonstrates how to create `EUI48` and `EUI64` objects, access various string representations, handle `ValueError` for invalid inputs, and define a custom hardware address type."},"warnings":[{"fix":"For retrieving MAC addresses from your system or network, use dedicated libraries like `getmac` (`pip install getmac`) or Python's built-in `uuid.getnode()` function.","message":"This library is designed solely for *parsing, validating, and manipulating* hardware address strings. It does *not* provide functionality to *retrieve* the MAC address of local network interfaces or remote hosts.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If OUI-to-vendor lookup is required, you will need to integrate with an external OUI database or use a library that provides this feature, such as `mactools` or `netaddr`.","message":"The `macaddress` library does not include built-in functionality for OUI (Organizationally Unique Identifier) lookups to vendor names. It focuses on the structural validation and representation of MAC addresses.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always review the project's changelog or release notes before upgrading to a new major version. Pinning dependency versions (e.g., `macaddress~=2.0`) is recommended for production environments.","message":"The library adheres to SemVer 2.0.0. While no immediate breaking changes are widely documented between recent minor versions, new major versions (e.g., 2.x.x to 3.x.x) may introduce breaking changes.","severity":"breaking","affected_versions":"Future major versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure the input string conforms to a standard MAC address format (e.g., '00-11-22-AA-BB-CC', '00:11:22:AA:BB:CC', '0011.22AA.BBCC', '001122AABBCC'). You can inspect the supported formats for a class using its `.formats` attribute (e.g., `macaddress.EUI48.formats`). If needed, subclass `HWAddress` to define custom acceptable formats.","cause":"An invalid string format was provided to a hardware address class constructor (e.g., `macaddress.EUI48()`). The string does not match any of the class's supported MAC address formats.","error":"ValueError: 'invalid-mac' cannot be parsed as EUI48"},{"fix":"The `macaddress` library is for parsing and validating MAC address strings, not for system discovery. If you need to retrieve the MAC address of a local network interface, use `from getmac import get_mac_address` (after `pip install getmac`) or `import uuid; uuid.getnode()` from the Python standard library.","cause":"Attempting to call a function like `get_mac_address()` directly from the `macaddress` module, confusing it with libraries like `getmac` that are designed to discover system MAC addresses.","error":"No attribute 'get_mac_address' on 'macaddress' module"}]}