Install & Compatibility
Where this runs
tested against v4.5.0 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.104s · 19.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.098s · 20MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
zxcvbn
✓ from zxcvbn import zxcvbn
✗ from zxcvbn_python import zxcvbn
The PyPI package `zxcvbn-python` was deprecated; the current, maintained package is simply `zxcvbn`.
This quickstart demonstrates how to import and use the `zxcvbn` function to evaluate password strength. It shows a basic check and an example of providing `user_inputs` to improve the accuracy of the strength calculation by penalizing common user-related patterns in the password. The output includes a score, crack time estimates, and feedback.
from zxcvbn import zxcvbn
# Basic password strength check
results = zxcvbn('password123')
print(f"Password: {results['password']}")
print(f"Score: {results['score']} (0=terrible, 4=great)")
print(f"Crack time display: {results['crack_times_display']['offline_fast_hashing_1e10_per_second']}")
if results['feedback'] and results['feedback']['suggestions']:
print("Suggestions:")
for suggestion in results['feedback']['suggestions']:
print(f"- {suggestion}")
# With user-provided inputs (e.g., username, name) to penalize matching patterns
user_inputs = ['John', 'Smith', 'jsmith']
results_with_user_input = zxcvbn('JohnSmith123', user_inputs=user_inputs)
print(f"\nPassword (with user inputs): {results_with_user_input['password']}")
print(f"Score: {results_with_user_input['score']}")
if results_with_user_input['feedback'] and results_with_user_input['feedback']['warning']:
print(f"Warning: {results_with_user_input['feedback']['warning']}")
Debug
Known issues
breakingThe official PyPI package name changed from `zxcvbn-python` to `zxcvbn`. Additionally, the original `dropbox/python-zxcvbn` GitHub repository is deprecated. Users should migrate to `pip install zxcvbn` and `from zxcvbn import zxcvbn` for the actively maintained version.fixUpdate your `requirements.txt` to `zxcvbn` and import statements to `from zxcvbn import zxcvbn`.
affects: < 4.4.25 (for `zxcvbn-python` PyPI), all (for `dropbox/python-zxcvbn` GitHub)
breakingOlder versions of `zxcvbn-python` supported Python 2.6-2.7. The current `zxcvbn` library (dwolfhub's fork) explicitly supports Python 3.8-3.13. Python 2 environments will not be compatible with the latest versions.fixUpgrade your Python environment to Python 3.8 or newer to use the latest `zxcvbn`.
affects: All versions from 4.4.25 onwards
gotchaSetting `max_length` for password inputs beyond approximately 72 characters can lead to significantly longer processing times. This may expose server-side applications to potential denial-of-service (DoS) scenarios due to the computational intensity of the algorithm. It is strongly advised against.fixImplement client-side or server-side truncation/validation for extremely long passwords before passing them to `zxcvbn`, or limit the `max_length` parameter if custom implementations allow it.
affects: All versions
gotchaThe lazy loading of ranked dictionaries within `zxcvbn` is not thread-safe. This can lead to race conditions or unexpected behavior in multi-threaded applications if multiple threads attempt to access or initialize these dictionaries concurrently.fixEnsure that the first call to `zxcvbn()` or any dictionary-loading mechanism occurs in a single-threaded context, or implement explicit locking around initialization if using the library in a multi-threaded environment.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'zxcvbn'
The zxcvbn package is not installed in the current Python environment.
NameError: name 'zxcvbn' is not defined
The zxcvbn function was called without being properly imported or referenced with the module prefix.
fixfrom zxcvbn import zxcvbn
result = zxcvbn('my_password') AttributeError: module 'zxcvbn' has no attribute 'Zxcvbn'
Developers sometimes incorrectly attempt to instantiate zxcvbn as a class (e.g., Zxcvbn()) instead of calling the top-level zxcvbn function directly.
fixfrom zxcvbn import zxcvbn
result = zxcvbn('my_password') # zxcvbn is a function, not a class to instantiate TypeError: zxcvbn() missing 1 required positional argument: 'password'
The zxcvbn function was called without passing the mandatory 'password' string argument.
fixfrom zxcvbn import zxcvbn
result = zxcvbn('my_password') Upgrade
Version history
4.5.0latest on PyPI · released Feb 19, 2025
Audit
Dependencies
pythonrequiredThe library is tested with Python versions 3.8-3.13.