Pwned Passwords Django

5.2.0 verified Fri May 01 auth: no python

A Django library to check passwords against the Have I Been Pwned Pwned Passwords database, either via k-Anonymity API or a local download of the hashed passwords. Version 5.2.0 requires Python >=3.9, compatible with Django 3.2+. It integrates seamlessly with Django's password validation framework and provides both online and offline modes.

pip install pwned-passwords-django

Common errors

error ModuleNotFoundError: No module named 'pwned_passwords' ↓

cause The package was renamed from django-pwned-passwords to pwned-passwords-django. The old module name is no longer available.

fix

pip install pwned-passwords-django and use 'from pwned_passwords_django import ...'

error pwned_password_validator is not a valid validator ↓

cause The validator is not added correctly to AUTH_PASSWORD_VALIDATORS. Common mistake: missing the full dotted path.

fix

Use 'NAME': 'pwned_passwords_django.validators.pwned_password_validator' in the validator dictionary.

error AttributeError: module 'pwned_passwords_django' has no attribute 'validate_password' ↓

cause The module does not export validate_password directly; it's inside validators module.

fix

from pwned_passwords_django.validators import pwned_password_validator

Warnings

gotcha The validator only works when the password is set via Django's set_password() which triggers validation. Direct assignment to the password field bypasses validation. ↓

fix Use set_password() or User.objects.create_user() to ensure validation runs.

gotcha If API_ENABLED is True (default), the validator makes an external API call to HIBP. This can cause performance issues in bulk operations or deny the service if misconfigured. ↓

fix Set PWNED_PASSWORDS['API_ENABLED'] = False and use a local database download for offline mode.

breaking In version 4.0.0, the package renamed from 'django-pwned-passwords' to 'pwned-passwords-django'. Import paths changed accordingly. ↓

fix Use the new package name: pip install pwned-passwords-django. Old import 'from pwned_passwords import ...' no longer works.

Imports

pwned_password_validator
```
from pwned_passwords_django.validators import pwned_password_validator
```
The validator is used in Django's AUTH_PASSWORD_VALIDATORS setting.

validate_password

wrong

from pwned_passwords_django import validate_password

correct

from pwned_passwords_django.validators import pwned_password_validator

validate_password is not a top-level export; use the validator class.

Quickstart

Basic setup: add app to INSTALLED_APPS, add the validator, and optionally configure API vs local mode.

# Add to INSTALLED_APPS:
INSTALLED_APPS = [
    ...
    'pwned_passwords_django',
]

# Add to AUTH_PASSWORD_VALIDATORS:
AUTH_PASSWORD_VALIDATORS = [
    ...
    {
        'NAME': 'pwned_passwords_django.validators.pwned_password_validator',
    },
]

# Optional: configure settings in settings.py
PWNED_PASSWORDS = {
    'API_ENABLED': True,  # or False to use local database
}