Install & Compatibility
Where this runs
tested against v5.1 · 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.688s · 85.6MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.0s · import 0.646s · 86MB
85MB installed
● package 85MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
USZipCodeField
✓ from localflavor.us.forms import USZipCodeField
✗ from localflavor.us.forms import SomeField
USStateField
✓ from localflavor.us.models import USStateField
✗ from localflavor.us.models import SomeField
USStateSelect
✓ from localflavor.us.forms import USStateSelect
✗ from localflavor.us.forms import SomeField
This example demonstrates creating a simple Django form using `USStateField` from `django-localflavor`. It includes minimal Django settings configuration to make the snippet runnable for demonstration purposes. Users would typically integrate this into an existing Django project's forms.py and views.py.
import os
from django import forms
from localflavor.us.forms import USStateField # Example: using a US-specific field
from django.conf import settings
# Minimal Django settings for standalone execution or in a Django project context
if not settings.configured:
settings.configure(
INSTALLED_APPS=[
'localflavor', # Required for translations and some internal workings
],
DEBUG=True,
SECRET_KEY=os.environ.get('DJANGO_SECRET_KEY', 'a-very-secret-key-for-testing-only'),
# Add other necessary settings like TEMPLATES, DATABASES for a full Django app
)
class MyUSForm(forms.Form):
state = USStateField()
city = forms.CharField(max_length=100)
# Example usage (e.g., in a Django view or a test)
def process_form_data():
# Simulate form submission
form_data = {'state': 'NY', 'city': 'New York'}
form = MyUSForm(form_data)
if form.is_valid():
print(f"Form is valid. State: {form.cleaned_data['state']}, City: {form.cleaned_data['city']}")
return form.cleaned_data
else:
print("Form is not valid. Errors:", form.errors)
return None
if __name__ == '__main__':
print("Processing valid form data:")
process_form_data()
print("\nProcessing invalid form data:")
invalid_form_data = {'state': 'XX', 'city': 'Invalid City'}
invalid_form = MyUSForm(invalid_form_data)
if not invalid_form.is_valid():
print("Form is not valid. Errors:", invalid_form.errors)
Debug
Known issues
breakingThe `django.contrib.localflavor` package was deprecated in Django 1.5 and removed in Django 1.6. All imports must be updated to `localflavor.<country_code>`.fixChange all `from django.contrib.localflavor...` imports to `from localflavor...`. Install the standalone `django-localflavor` package.
affects: Django 1.5 and newer (for the 'django-localflavor' library, this affects all versions that depend on it being a separate package).
breakingVersion 3.0 removed all previously deprecated code. Ensure you have addressed all `DeprecationWarning` messages if upgrading from versions prior to 3.0.fixRun your project's tests with `python -Wd` to display deprecation warnings and update code accordingly before upgrading to 3.0 or later.
affects: <3.0
breakingSpecific local flavors (e.g., LV, NP, NO in 5.0; MX, IN in 3.1) have had breaking data changes due to updates in official governmental policies or data structures.fixConsult the changelog for `django-localflavor` for the specific version you are upgrading to, particularly if using affected country flavors, and update your data or expectations accordingly.
affects: 5.0 (LV, NP, NO), 4.0, 3.1 (MX, IN) and potentially future major versions.
deprecateddjango-localflavor no longer accepts contributions for country-specific phone number fields and has removed its own. For robust phone number validation, the `django-phonenumber-field` package is recommended.fixMigrate any existing phone number fields to use `django-phonenumber-field` for better and more comprehensive support.
affects: All versions (policy change, not a specific breaking version removal).
gotchaFor localflavor's text (e.g., form field error messages) to be translated, `localflavor` must be included in your Django project's `INSTALLED_APPS` setting.fixAdd `'localflavor'` to your `INSTALLED_APPS` list in `settings.py`.
affects: All versions.
gotchaBackwards-incompatible changes can occur due to updates reflecting officially gazetted policies of local government authorities (e.g., removal or renaming of a province). These changes will raise a runtime warning when the affected localflavor is imported.fixMonitor for runtime warnings related to localflavor imports and review the changelog for details on specific country flavor updates that might require code or data adjustments.
affects: All versions, as these reflect real-world changes.
Upgrade
Version history
5.1latest on PyPI · released Aug 1, 2026
Audit
Dependencies
DjangorequiredCore dependency for all functionality.
django-phonenumber-fieldoptionalRecommended for country-specific phone number fields, as django-localflavor no longer accepts contributions for these.