Install & Compatibility
Where this runs
tested against v2026.7.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.312s · 55.6MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 3.0s · import 0.277s · 55MB
53MB installed
● package 53MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
IBAN
✓ from schwifty import IBAN
BIC
✓ from schwifty import BIC
This quickstart demonstrates how to initialize `IBAN` and `BIC` objects, access their components, and generate new IBANs. Validation happens automatically upon instantiation, raising a `ValueError` (or a more specific `SchwiftyException` subclass) for invalid inputs.
from schwifty import IBAN, BIC
# Validate and parse an IBAN
try:
iban = IBAN('DE89 3704 0044 0532 0130 00')
print(f"IBAN: {iban.formatted}")
print(f"Country Code: {iban.country_code}")
print(f"Bank Code: {iban.bank_code}")
print(f"Account Code: {iban.account_code}")
print(f"BIC (if available): {iban.bic}")
except ValueError as e:
print(f"Invalid IBAN: {e}")
# Generate an IBAN
generated_iban = IBAN.generate('GB', bank_code='040004', account_code='34340004')
print(f"Generated IBAN: {generated_iban.formatted}")
# Create and validate a BIC
try:
bic = BIC('COBADEFFXXX')
print(f"BIC: {bic.formatted}")
print(f"Country Code: {bic.country_code}")
except ValueError as e:
print(f"Invalid BIC: {e}")
Debug
Known issues
breakingSchwifty has periodically removed support for older Python versions. Python 3.9 was dropped in v2026.01.0, and Python 3.8 in v2024.11.0. The library currently requires Python 3.10 or newer.fixUpgrade your Python environment to version 3.10 or a newer compatible version.
affects: All versions since 2024.11.0
gotchaWhen integrating Schwifty's IBAN/BIC types with Pydantic, strict validation is enabled by default. To allow more lax validation (e.g., ignoring whitespace or formatting differences), the field must be explicitly annotated with `Field(strict=False)`.fixFor Pydantic models, use `iban: Annotated[IBAN, Field(strict=False)]` to allow lax validation.
affects: 2025.07.0 and later
breakingThe base exception class for all validation failures changed from `ValueError` to `SchwiftyException` (which subclasses `ValueError`) in version 2021.01.0. While catching `ValueError` will still work, direct catches of `ValueError` might be too broad. `SchwiftyException` offers more specific error subclasses for granular handling.fixUpdate exception handling to catch `SchwiftyException` or its more specific subclasses (e.g., `InvalidCountryCode`, `InvalidChecksum`) for `schwifty`-related validation errors.
affects: 2021.01.0 and later
gotchaPrior to version 2025.09.0, the Polish IBAN format override could lead to unusual bank code breakdowns when generating IBANs from individual components. This could result in incorrectly structured IBANs if not thoroughly validated.fixEnsure you are using `schwifty` version 2025.09.0 or newer when generating Polish IBANs. For older versions, meticulously validate any generated Polish IBANs.
affects: Versions prior to 2025.09.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'schwifty'
The 'schwifty' package is not installed or not accessible in the current Python environment.
fixRun 'pip install schwifty' in your terminal to install the library.
schwifty.exceptions.InvalidFormatException: IBAN 'XYZ' has invalid characters
The input string provided to the IBAN or BIC constructor contains characters not allowed or does not conform to the expected format (e.g., incorrect length, invalid checksum, non-alphanumeric characters).
fixEnsure the input string is a valid IBAN or BIC according to ISO standards. For example, 'DE89370400440532013000' is a valid IBAN. You can also use `IBAN.is_valid()` or `BIC.is_valid()` to validate without raising an exception.
ModuleNotFoundError: No module named 'schwifty.IBAN'
The user is attempting to import the 'IBAN' class as if it were a submodule of 'schwifty', but it is a class directly available from the top-level 'schwifty' package.
fixImport the 'IBAN' class directly from the 'schwifty' package using 'from schwifty import IBAN' (and 'BIC' if needed).
TypeError: 'int' object is not iterable
The IBAN or BIC constructor was called with a non-string argument (e.g., an integer or float) instead of the required string representing the account or identifier.
fixAlways provide the IBAN or BIC constructor with a string argument. For example, 'IBAN('DE89370400440532013000')' instead of 'IBAN(123)'. Upgrade
Version history
2026.7.3latest on PyPI · released Jul 23, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.10 or newer for current versions.
importlib-resourcesrequiredUsed for accessing package data, conditionally for Python <= 3.11.
pycountryrequiredUsed for country-specific data.
rstrrequiredUsed for generating random strings for IBAN/BIC generation.
typing-extensionsrequiredBackports of typing features, conditionally for Python <= 3.10.
pydanticoptionalEnables direct usage of IBAN and BIC types with Pydantic models for data validation. Requires `pydantic >= 2.0`.