Skip to main content

A CLI tool and Python3 module for looking up hardware MAC addresses from the published OUI source at

Project description


PyPi Python Versions build tests License

A CLI tool and Python3 module for looking up hardware MAC addresses from the published OUI source list at



via PyPi

pip3 install ouilookup

Arch Linux (via AUR, and your favorite AUR-helper)

yay -S ouilookup-py3

via Source

git clone
cd ouilookup
python3 -m venv venv
source venv/bin/activate
pip3 install -r requirements.txt
python3 clean
python3 test
python3 install


Legacy versions based on year-date (eg v2018.2) have been hard-deprecated in favour of a backward incompatible standard versioning scheme (eg v0.2.0).

CLI usage

usage: ouilookup [-h] [-q <hwaddr> | -u | -un | -s] [-d]

ouilookup v0.0.2

optional arguments:
  -h, --help            show this help message and exit
  -q <hwaddr>, --query <hwaddr>
                        Query to locate matching MAC hardware address(es) from
                        the oui database. Addresses may be expressed in
                        formats with or without ":" or "-" separators. Use a
                        space between addresses for more than one lookup in a
                        single query line.
  -u, --update          Download the latest oui.txt from "standards-
              " and parse it to generate a local
                        oui.json for use by OuiLookup. The following paths (in
                        order) are examined for write-access to save the
                        oui.json data-file: /var/lib/ouilookup
  -un, --update-no-download
                        Parse the oui.txt file in the data-path and update the
                        local oui.json data-file without downloading the
                        latest oui.txt update from "".
  -s, --status          Return status information about the oui.json data-file
                        available to OuiLookup.

  -d, --debug           Provide debug logging output to stderr.

A CLI tool for interfacing with the OuiLookup module that provides CLI access
the query(), update() and status() functions. Outputs at the CLI are JSON
formatted thus allowing for easy chaining to other toolchains. The update()
function updates directly from "" and the ouilookup
package provides an internal fallback oui.txt updated at time of packaging.

Python3 Module usage

>>> from OuiLookup import OuiLookup

>>> OuiLookup().query('00:00:aa:00:00:00')
[{'0000AA000000': 'XEROX CORPORATION'}]

>>> OuiLookup().query('00:00:01:00:00:00 00-00-10-00-00-00 000011000000')
[{'000001000000': 'XEROX CORPORATION'}, {'000010000000': 'SYTEK INC.'}, {'000011000000': 'NORMEREL SYSTEMES'}]

>>> OuiLookup().update()
{'timestamp': '20200218Z234257', 'source_uri': '', 'source_bytes': 4359180, 'source_md5': 'd901b821bbe2506e5837a1a522b48be6', 'source_sha1': '15511c01f00de7b4b9c03f081fc09693fca0f9ca', 'source_sha256': 'a32da3183b0e683082cdf35c85da78d407e017465f184dbd4f6aecd405e561eb', 'vendor_count': 27550}

>>> OuiLookup().status()
{'source_bytes': 4359180, 'source_md5': 'd901b821bbe2506e5837a1a522b48be6', 'source_sha1': '15511c01f00de7b4b9c03f081fc09693fca0f9ca', 'source_sha256': 'a32da3183b0e683082cdf35c85da78d407e017465f184dbd4f6aecd405e561eb', 'source_uri': '', 'timestamp': '20200218Z234257', 'vendor_count': 27550, 'data_path': '/usr/local/lib/python3.6/dist-packages/ouilookup/data', 'data_file': '/usr/local/lib/python3.6/dist-packages/ouilookup/data/oui.json'}



BSD-2-Clause - see LICENSE file for full details.

NB: License change from Apache-2.0 to BSD-2-Clause in February 2020 at version 0.2.0

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

ouilookup-0.2.4.tar.gz (1.6 MB view hashes)

Uploaded source

Built Distribution

ouilookup-0.2.4-py3-none-any.whl (1.6 MB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page