py-machineid

1.0.0 · active · verified Thu Apr 16

py-machineid is a Python library designed to retrieve the unique machine ID (UUID/GUID) of any host without requiring administrative privileges. It extracts the operating system's native machine identifier, which is generally stable for a given OS installation. The library also offers a cryptographically hashed version of the ID, useful for application-specific identification. The current version is 1.0.0, and it maintains an active development status, with updates released as needed for bug fixes and feature enhancements.

Common errors

```
ModuleNotFoundError: No module named 'machineid'
```
cause The `py-machineid` package has not been installed in your current Python environment.

fix Run `pip install py-machineid` in your terminal to install the library.
```
TypeError: 'str' object is not callable
```
cause You are attempting to use `machineid.id` or `machineid.hashed_id` as a variable or property rather than calling it as a function. Functions require parentheses `()` to be executed.

fix Call the functions with parentheses: `machineid.id()` or `machineid.hashed_id('your-app-id')`.
```
ValueError: Invalid application ID, must be a string.
```
cause You passed a non-string value (e.g., `None` or an integer) to the `hashed_id()` function as the application ID. The `app_id` parameter must be a string.

fix Ensure that the `app_id` argument passed to `machineid.hashed_id()` is always a string, for example: `machineid.hashed_id('my_application')`.

Warnings

breaking The `hashed_id()` function's order of operations for HMAC computation was fixed in v1.0.0 to match the Go `machineid` package. This is a breaking change for all previously generated hashed IDs.
Fix: If you were using `hashed_id()` prior to v1.0.0 and relied on its persistence, note that existing hashed IDs will no longer match. Update any systems or databases that depend on these values accordingly.
gotcha On Windows, `id()` and `hashed_id()` query the registry by default. This behavior can be disabled using the `winregistry=False` keyword argument. Disabling it might prevent manual modification of machine fingerprints but could alter the ID generated.
Fix: Consider your security posture and desired ID consistency. If you need to prevent potential fingerprint tampering via registry modification, use `machineid.id(winregistry=False)` or `machineid.hashed_id(app_id, winregistry=False)`.
gotcha Machine IDs, while generally stable per OS installation, can be changed by a root/admin user (e.g., by modifying `/var/lib/dbus/machine-id` on Linux or using `sysprep` on Windows). Cloned or imaged systems might also retain the original ID if not properly prepared.
Fix: Be aware that the ID is not immutable. For application-specific, non-admin-alterable unique IDs, consider using `hashed_id()` with a unique `app_id` to add an additional layer of distinction.
gotcha A `SyntaxWarning: invalid escape sequence '\S'` may be emitted when importing `machineid` with Python 3.12 due to a regex pattern.
Fix: This is typically a warning and doesn't prevent the library from functioning correctly. It can be ignored or suppressed. A future library update may address this directly.
gotcha The machine ID uniquely identifies the host and should be treated as confidential information. Directly exposing it in untrusted environments is a security risk.
Fix: For identifying an application instance on a machine, use `machineid.hashed_id('your_application_identifier')` instead of `machineid.id()`. The hashed ID is cryptographically secure and suitable for public-facing use.

Install

pip install py-machineid Install latest version

Imports

id
```
import machineid
machineid.id()
```
Imports the library and calls the 'id' function to get the raw machine ID.
hashed_id
```
import machineid
machineid.hashed_id('your-application-id')
```
Imports the library and calls the 'hashed_id' function with an application ID for an anonymized, application-specific identifier.

Quickstart

This quickstart demonstrates how to retrieve both the raw, native machine ID and an anonymized, application-specific hashed ID. It also shows how to optionally disable the Windows registry query for added control over fingerprinting. Error handling is included for robust usage.

import machineid

# Get the raw, native machine ID (GUID/UUID)
try:
    device_id = machineid.id()
    print(f"Raw Machine ID: {device_id}")
except Exception as e:
    print(f"Error getting raw machine ID: {e}")

# Get an anonymized (hashed) version of the ID for a specific application
app_id = "my-unique-application"
try:
    hashed_device_id = machineid.hashed_id(app_id)
    print(f"Hashed Machine ID (for '{app_id}'): {hashed_device_id}")
except Exception as e:
    print(f"Error getting hashed machine ID: {e}")

# Disable Windows registry query (if applicable) for id()
try:
    win_id_no_reg = machineid.id(winregistry=False)
    print(f"Raw Machine ID (no winregistry): {win_id_no_reg}")
except Exception as e:
    print(f"Error getting raw machine ID (no winregistry): {e}")

view raw JSON →