MAC Address Library

2.0.2 · active · verified Thu Apr 16

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.

Common errors

```
ValueError: 'invalid-mac' cannot be parsed as EUI48
```
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.

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.
```
No attribute 'get_mac_address' on 'macaddress' module
```
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.

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.

Warnings

gotcha 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.
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.
gotcha 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.
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`.
breaking 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.
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.

Install

pip install macaddress Install stable version

Imports

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.

Quickstart

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}")

view raw JSON →