Registry / web-framework / django-localflavor

django-localflavor

JSON →
library5.1pypypi✓ verified 28d ago

django-localflavor is a collection of country-specific Django helpers, including form fields, form widgets, and model fields, useful for particular countries or cultures. It provides localized components for postal codes, government IDs, and regional selections. Originally part of Django's `contrib` apps, it was extracted into a separate package starting with Django 1.5 for easier maintenance. The current version is 5.0, and new releases generally follow Django's major version number, with a compatible version released within one month of each Django release.

pip install django-localflavor
INSTALL
IMPORT
SIG · DJANGO-LOCALFLAVOR
D
django-localflavor
web-frameworkpythonv5.1
Install
4.0s avg
Import
667ms
Disk
85MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
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
musl
py 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.688s · 85.6MB
glibc
py 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>`.
fix
Change 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.
fix
Run 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.
fix
Consult 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.
fix
Migrate 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.
fix
Add `'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.
fix
Monitor 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.
Agent activity
11 hits · last 30 days
node
10
Resources
django-localflavor — pip install django-localflavor · libregistry