iban_validation_py

A package to facilitate validation of IBANs and getting the bank identifier and branch identifier in Python.

Short examples

There are four ways to interact with the API:

• Validate the iban with validate_iban this does not indicate what is incorrect when the iban in invalid.
• Validate the iban with validate_iban_with_error does the same and give an error message when the iban is invalid.
• Validate the iban with validate_iban_error_code which returns an error code (0 for valid, 1-6 for specific errors).
• create an IbanValidation which allows to select the validated iban, the branch_id and bank_id when relevant.

See below code for illustration:

import iban_validation_py
from iban_validation_py import IbanValidation

result = iban_validation_py.validate_iban('AL47212110090000000235698741')
assert(result is True)
result = iban_validation_py.validate_iban('AL47212110090000000235698741VV')
assert(result is False)
result, message = iban_validation_py.validate_iban_with_error('AL47212110090000000235698741VV')
assert(result is False)
assert(message == 'IBAN Validation failed: The length of the input Iban does match the length for that country')   

# Using error codes
error_code = iban_validation_py.validate_iban_error_code('AL47212110090000000235698741')
assert(error_code == iban_validation_py.ERROR_VALID)

error_code = iban_validation_py.validate_iban_error_code('AL47212110090000000235698741VV')
assert(error_code == iban_validation_py.ERROR_INVALID_SIZE)

# Check specific error types
if error_code == iban_validation_py.ERROR_TOO_SHORT:
    print("IBAN is too short")
elif error_code == iban_validation_py.ERROR_MISSING_COUNTRY:
    print("IBAN missing country code")
elif error_code == iban_validation_py.ERROR_INVALID_COUNTRY:
    print("Invalid country code")
elif error_code == iban_validation_py.ERROR_STRUCTURE_INCORRECT:
    print("IBAN structure doesn't match country requirements")
elif error_code == iban_validation_py.ERROR_INVALID_SIZE:
    print("IBAN length doesn't match country requirements")
elif error_code == iban_validation_py.ERROR_MODULO_INCORRECT:
    print("IBAN checksum is incorrect")

result = iban_validation_py.validate_print_iban('AL47 2121 1009 0000 0002 3569 8741')
assert result is True

# # Valid IBAN
iban = IbanValidation('AL47212110090000000235698741')
assert('AL47212110090000000235698741' == iban.stored_iban)
assert('212' == iban.iban_bank_id)
assert('11009' == iban.iban_branch_id)

Non-registry countries

By default, only the official SWIFT IBAN registry countries validate. Pass the keyword-only allow_non_registry=True to any validation function, or to IbanValidation, to additionally accept 22 IBAN-shaped account numbers that are not in the official registry (community-sourced, weaker guarantees):

iban_validation_py.validate_iban("AO49012345678901234567890")  # False (default)
iban_validation_py.validate_iban("AO49012345678901234567890", allow_non_registry=True)  # True

iban = IbanValidation("AO49012345678901234567890", allow_non_registry=True)
assert iban.is_non_registry is True

# the set of two-letter codes accepted only with allow_non_registry=True
assert "AO" in iban_validation_py.NON_REGISTRY_COUNTRIES

allow_non_registry defaults to False everywhere, so existing code is unaffected.

Error Codes

The validate_iban_error_code function returns the following error codes:

• ERROR_VALID (0): The IBAN is valid
• ERROR_TOO_SHORT (1): The IBAN is too short (minimum length is 4)
• ERROR_MISSING_COUNTRY (2): The IBAN doesn't start with a two-letter country code
• ERROR_INVALID_COUNTRY (3): The country code is not recognized
• ERROR_STRUCTURE_INCORRECT (4): The IBAN structure doesn't match the country's requirements
• ERROR_INVALID_SIZE (5): The IBAN length doesn't match the expected length for that country
• ERROR_MODULO_INCORRECT (6): The IBAN checksum (mod97) is incorrect
• ERROR_INVALID_CHECKSUM (7): The check digits are one of the forbidden values (00, 01 or 99)

Type hints

The package ships inline type stubs (__init__.pyi) and a PEP 561 py.typed marker, so editors and type checkers (mypy, pyright) resolve the signatures of every function and of IbanValidation without any extra stub package.

Credit

Cheers to the Pyo3 Maturin project! It made this package possible.

Changes

• 0.1.30: updated to registry version 103 (a change to Brazil IBAN definition). rust updated to 1.99.0.
• 0.1.29: added the ERROR_INVALID_CHECKSUM (7) constant, which validate_iban_error_code could already return; added inline type stubs (py.typed + __init__.pyi) so the package is typed for mypy/pyright; added opt-in allow_non_registry keyword argument (default False) to every validation function and to IbanValidation, plus IbanValidation.is_non_registry and the NON_REGISTRY_COUNTRIES constant.
• 0.1.28: upgraded to polars 0.54.4, rust 1.96.1, update to iban registry version 102 from Jun 2026 (no significant changes for this package)
• 0.1.27: upgraded to polars 0.53.0, rust 1.93.1
• 0.1.26: added user_friendly iban validation (handle spaces), added compile time checks, and updated to rust 1.93, dropping python 3.9, adding python 3.14
• 0.1.25: added forbidden checksums in the validation
• 0.1.24: added validate_iban_error_code function to return specific error codes for validation failures.
• 0.1.23: upgraded to latest Iban register (version 101), only change Portugal (no branch anymore). updated to rust 1.92.0.
• 0.1.22: upgraded to latest Iban register (version 100), only Albania (AL) and Poland (PL) have changes affecting this project. updated to rust 1.91.1.
• 0.1.21: upgraded to polars 0.52.0, rust 1.91, improved internal data structure. Enable modern CPU instruction on x86 (x86-64-v3) and Mac (M1) for python, polars and c packages.
• 0.1.20: technical update upgraded to polars 0.51.0, rust 1.90
• 0.1.19: technical update upgraded to polars 0.50.0, rust 1.89
• 0.1.18: technical update upgraded to polars 0.49.1, pyo3 0.25, rust 1.88
• 0.1.17: memory usage reduced.
• 0.1.16: improved performance, added territories for GB and FR, and more tests, added WASM (experimental for now), added fuzzer.
• 0.1.15: improved performance (char to bytes) and improved c wrapper doc.
• 0.1.14: fixed error for country code IQ (using pdf instead of technicql input file).
• 0.1.11: eliminated rust dependecies (rust code generated from Python instead of Hash and Serde).
• 0.1.9: improve mod97 perf (reduce memory needed).
• 0.1.8: improve mod97 perf (cpu memory tradeoff).
• 0.1.7: improve performance related to the Iban structure again.
• 0.1.6: improve performance related to the Iban structure.
• 0.1.5: added support to Python 3.13.
• 0.1.4: technical update; updated polars dependency to polars 0.46.0, and py03 0.23 impacting only the Python packages.