zxcvbn Type Stubs

4.5.0.20260408 · active · verified Thu Apr 16

types-zxcvbn is a PEP 561 type stub package providing static type annotations for the zxcvbn library, a realistic password strength estimator. It is part of the typeshed project and is designed to be used by type checkers like MyPy or Pyright. This package aims to provide accurate annotations for zxcvbn==4.5.* and is updated regularly as part of typeshed's release cycle, often daily.

Common errors

```
ModuleNotFoundError: No module named 'zxcvbn'
```
cause The `types-zxcvbn` package provides type definitions but does not install the actual `zxcvbn` runtime library, which is necessary for execution.

fix Install the `zxcvbn` library: `pip install zxcvbn`.
```
TypeError: 'module' object is not callable
```
cause This error typically occurs when attempting to call the `zxcvbn` module directly (e.g., `import zxcvbn; zxcvbn('password')`) instead of importing and calling the `zxcvbn` function *within* the module.

fix Correct the import and call pattern to `from zxcvbn import zxcvbn; results = zxcvbn('password')`.
```
Type checker reports 'Missing type stub for 'zxcvbn'' or similar, even after installing 'types-zxcvbn'.
```
cause This can happen if your type checker is not configured to find third-party stubs, or if there's a version mismatch between the installed `zxcvbn` library and the `types-zxcvbn` stubs.

fix Ensure your type checker (e.g., MyPy, Pyright) is properly configured to use installed stub packages. Verify that the version of `types-zxcvbn` you have installed is compatible with your `zxcvbn` runtime library version.

Warnings

gotcha Installing `types-zxcvbn` alone only provides type hints for static analysis; it does NOT install the actual runtime `zxcvbn` library. You must install `zxcvbn` separately (e.g., `pip install zxcvbn`) for your code to run successfully.
Fix: Always ensure both `zxcvbn` and `types-zxcvbn` are installed: `pip install zxcvbn types-zxcvbn`.
breaking Type checking failures may occur if the version of `types-zxcvbn` does not accurately match the version of the `zxcvbn` runtime library you are using. `types-zxcvbn` aims to provide annotations for `zxcvbn==4.5.*`.
Fix: Align the major and minor versions of `types-zxcvbn` with your `zxcvbn` installation. For example, if you use `zxcvbn>=4.5.0,<4.6`, use `types-zxcvbn>=4.5.0,<4.6`.
gotcha There are multiple Python implementations/forks of `zxcvbn`, some of which are deprecated or unmaintained (e.g., `dropbox/python-zxcvbn`). The currently recommended and most up-to-date Python port is `dwolfhub/zxcvbn-python` (which corresponds to the `zxcvbn` package on PyPI).
Fix: Always install the `zxcvbn` package from PyPI (`pip install zxcvbn`) to ensure you are using the maintained version compatible with these type stubs. Avoid installing directly from old GitHub repositories unless you understand the implications.
gotcha Using the `max_length` parameter in the `zxcvbn` runtime library with values greater than 72 can lead to significantly longer processing times. This can potentially expose server-side applications to denial-of-service (DoS) scenarios.
Fix: Avoid setting `max_length` greater than 72. Consider truncating input passwords before passing them to `zxcvbn` if extremely long passwords are not expected or if performance is critical. Check the `zxcvbn` library's documentation for the latest recommendations.

Install

pip install types-zxcvbn zxcvbn Install with runtime dependency
pip install types-zxcvbn Install stubs only (requires zxcvbn separately)

Imports

zxcvbn
wrong:
```
import zxcvbn; zxcvbn.password_strength('test')
```
correct:
```
from zxcvbn import zxcvbn
```
The primary callable is named `zxcvbn` within the `zxcvbn` module itself. Older forks or versions might use `password_strength`.

Quickstart

This quickstart demonstrates how to import the `zxcvbn` function and use it to evaluate a password's strength, providing user inputs to penalize common personal information. The results dictionary contains detailed information, including a score, crack time estimates, and feedback.

from zxcvbn import zxcvbn

password = 'correct horse battery staple'
user_inputs = ['correct', 'horse', 'battery', 'staple']

# Evaluate password strength
results = zxcvbn(password, user_inputs=user_inputs)

print(f"Password: {results['password']}")
print(f"Score: {results['score']}/4 (0=terrible, 4=great)")
print(f"Feedback: {results['feedback']['suggestions']}")
print(f"Estimated crack time: {results['crack_times_display']['online_no_throttling_10_per_second']}")

view raw JSON →