Python Standardized Numbers and Codes

2.2 · active · verified Fri Apr 10

python-stdnum is a Python module designed to parse, validate, and reformat a large collection of standardized numbers and codes from various countries and international standards. Currently at version 2.2, released in January 2026, the library maintains a frequent release cadence, regularly adding support for new number formats, applying bug fixes, and enhancing existing functionalities.

Warnings

breaking Version 2.0 (released May 2025) dropped support for Python 2.x. It now requires Python 3.8 or newer. Attempts to install or run on older Python versions will fail.
Fix: Ensure your project's Python environment is version 3.8 or later before upgrading to python-stdnum 2.0 or newer.
gotcha The `validate()` function raises specific exceptions (e.g., `InvalidChecksum`, `InvalidLength`) for invalid numbers, which can halt execution if not handled. In contrast, `is_valid()` returns a boolean (`True` or `False`) and never raises an exception. Choose the appropriate function based on your error handling strategy.
Fix: Wrap `validate()` calls in `try...except stdnum.exceptions.StdnumException` blocks or use `is_valid()` for simple boolean checks. For example, `try: stdnum.isbn.validate(num) except stdnum.exceptions.InvalidChecksum: ...`
gotcha The `compact()` function generally does not perform full validation but may raise exceptions for 'wildly incorrect' inputs. The `format()` function also expects a valid number and may raise exceptions if an invalid number is passed to it.
Fix: It is best practice to `validate()` a number before attempting to `compact()` or `format()` it, especially if the input source is untrusted or prone to errors.

Install

pip install python-stdnum Install latest version

Imports

isbn
```
from stdnum import isbn
```
Common pattern for importing a specific number format module (e.g., 'isbn', 'us.ssn', 'nl.btw').
get_cc_module
```
from stdnum import get_cc_module
```
Used for dynamically retrieving a country-specific module by country code and name (e.g., `get_cc_module('nl', 'vat')`).

Quickstart

This quickstart demonstrates how to validate and format an International Standard Book Number (ISBN) using `stdnum.isbn`. It shows how to catch validation-related exceptions and how to use `is_valid()` for a boolean check without exceptions.

from stdnum import isbn
from stdnum.exceptions import InvalidChecksum, InvalidLength

# Validate an ISBN
try:
    validated_isbn = isbn.validate('978-0471117094')
    print(f"Validated ISBN: {validated_isbn}")
except (InvalidChecksum, InvalidLength) as e:
    print(f"Validation failed: {e}")

# Format an ISBN
formatted_isbn = isbn.format('9780471117094')
print(f"Formatted ISBN: {formatted_isbn}")

# Check validity without raising exceptions
is_valid = isbn.is_valid('978-0471117094')
print(f"Is valid (using is_valid): {is_valid}")

view raw JSON →