Luhn Check Digit Generator and Verifier

0.2.0 · maintenance · verified Thu Apr 16

The `luhn` Python library, currently at version 0.2.0, provides a simple and lightweight implementation of the Luhn algorithm. It's designed to generate and verify Luhn check digits for identification numbers, commonly used for credit cards and other IDs to detect accidental errors. This version was released in 2015 and has a stable, albeit minimal, API.

Common errors

```
ValueError: invalid literal for int() with base 10:
```
cause The input string contained non-digit characters (e.g., spaces, hyphens, letters) which cannot be converted to an integer by the library's internal `map(int, string)` call.

fix Pre-process the input string to remove any non-digit characters. Example: `cleaned_number = input_string.strip().replace(' ', '').replace('-', '')`.
```
TypeError: 'int' object is not iterable
```
cause An integer was passed to a function (e.g., `verify`, `generate`, `append`) that expects a string of digits.

fix Convert the integer to a string before passing it to the `luhn` functions. Example: `verify(str(12345))`.
```
Incorrect Luhn validation result for long numbers or specific patterns.
```
cause This is typically not a bug in the `luhn` library itself (which correctly implements the standard algorithm), but rather a misunderstanding of the Luhn algorithm's limitations, such as its inability to detect certain transposition errors (e.g., 09-90).

fix Review the specifications of the Luhn algorithm to understand its inherent strengths and weaknesses. If more robust error detection is needed, consider alternative checksums.

Warnings

gotcha The `luhn` library expects string input consisting solely of digits. Passing non-digit characters (e.g., spaces, hyphens, letters) will result in a `ValueError` during the internal conversion to integers.
Fix: Ensure input strings are stripped of any non-digit characters before passing them to `verify`, `generate`, or `append`. For example, `number_string.replace(' ', '').replace('-', '')`.
gotcha The Luhn algorithm itself is designed to detect single-digit errors and most adjacent digit transpositions, but it is not cryptographically secure and will not detect all types of transcription errors (e.g., '09' to '90' transposition).
Fix: For applications requiring higher security or more robust error detection, consider alternative or additional checksum algorithms, such as Verhoeff or Damm algorithms, or cryptographic hash functions.
deprecated This library (version 0.2.0, released in 2015) is older and may not receive active development or updates. Newer, more actively maintained Luhn implementations (e.g., `luhncheck`) are available on PyPI, offering additional features or potentially better performance.
Fix: While functional for basic Luhn operations, consider evaluating more recent alternatives like `luhncheck` if your project requires new features, active maintenance, or broader compatibility.

Install

pip install luhn Install with pip

Imports

verify
```
from luhn import verify
```
generate
```
from luhn import generate
```
append
```
from luhn import append
```
*
```
from luhn import *
```
Commonly used for convenience to import all functions, but explicit imports are generally recommended for clarity.

Quickstart

Demonstrates how to verify a number, generate a check digit, and append a check digit using the `luhn` library's primary functions.

from luhn import verify, generate, append

# Verify a Luhn compliant string
valid_number = '79927398713'
invalid_number = '79927398710'
print(f"'{valid_number}' is valid: {verify(valid_number)}")
print(f"'{invalid_number}' is valid: {verify(invalid_number)}")

# Generate a check digit for a string
base_number = '53461861341123'
check_digit = generate(base_number)
print(f"Check digit for '{base_number}' is: {check_digit}")

# Append a check digit to a string
appended_number = append(base_number)
print(f"'{base_number}' with check digit appended: {appended_number}")

view raw JSON →