Install & Compatibility
Where this runs
tested against v2.0.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 17.8MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 1.5s · import 0.000s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
macaddress
✓ import macaddress
Primary import for the library's functionality.
EUI48
✓ from macaddress import EUI48
Used for representing EUI-48 MAC addresses (also aliased as MAC).
EUI64
✓ from macaddress import EUI64
Used for representing EUI-64 addresses.
OUI
✓ from macaddress import OUI
Used for representing Organizationally Unique Identifiers.
HWAddress
✓ from macaddress import HWAddress
Base class for defining custom hardware address types.
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.
import macaddress
# Create an EUI48 (MAC) address object
mac = macaddress.EUI48('01-23-45-67-89-ab')
print(f"MAC Address: {mac}")
# Access different formats
print(f"MAC in colon format: {mac.colon}")
print(f"MAC in period format: {mac.period}")
print(f"MAC as bytes: {mac.packed}")
# Validate an address string
try:
invalid_mac = macaddress.EUI48('foo bar')
except ValueError as e:
print(f"Error parsing invalid MAC: {e}")
# Create an EUI64 address
eui64 = macaddress.EUI64('01-23-45-67-89-ab-cd-ef')
print(f"EUI64 Address: {eui64}")
# Define a custom format (example from docs)
class CustomMAC(macaddress.MAC):
formats = macaddress.MAC.formats + (
'xx-xx-xx-xx-xx-xx-xx-xx-xx-xx-xx-xx-xx-xx-xx-xx-xx-xx-xx-xx',
)
custom_mac = CustomMAC('01-23-45-67-89-AB-01-23-45-67-89-AB-01-23-45-67-89-AB')
print(f"Custom MAC: {custom_mac}")
Debug
Known issues
gotchaThis 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.fixFor retrieving MAC addresses from your system or network, use dedicated libraries like `getmac` (`pip install getmac`) or Python's built-in `uuid.getnode()` function.
affects: All versions
gotchaThe `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.fixIf 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`.
affects: All versions
breakingThe 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.fixAlways 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.
affects: Future major versions
Errors
Common errors & fixes
ValueError: 'invalid-mac' cannot be parsed as EUI48
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.
fixEnsure 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.
No attribute 'get_mac_address' on 'macaddress' module
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.
fixThe `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.
Upgrade
Version history
2.0.2latest on PyPI · released Nov 4, 2022
Audit
Dependencies
No dependency data recorded yet.