{"id":4510,"library":"django-localflavor","title":"Django Local Flavor","description":"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.","status":"active","version":"5.0","language":"en","source_language":"en","source_url":"https://github.com/django/django-localflavor","tags":["django","forms","localization","validation","country-specific"],"install":[{"cmd":"pip install django-localflavor","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core dependency for all functionality.","package":"Django","optional":false},{"reason":"Recommended for country-specific phone number fields, as django-localflavor no longer accepts contributions for these.","package":"django-phonenumber-field","optional":true}],"imports":[{"note":"The 'localflavor' package was moved out of Django's `contrib` in Django 1.5. Imports from `django.contrib.localflavor` ceased to work in Django 1.6.","wrong":"from django.contrib.localflavor.<country_code>.forms import SomeField","symbol":"SomeField","correct":"from localflavor.<country_code>.forms import SomeField"},{"note":"For translations of form field error messages, 'localflavor' must be included in `INSTALLED_APPS`. The old `django.contrib.localflavor` is deprecated and will raise warnings.","wrong":"INSTALLED_APPS = ['django.contrib.localflavor', ...]","symbol":"localflavor","correct":"INSTALLED_APPS = ['localflavor', ...]"}],"quickstart":{"code":"import os\nfrom django import forms\nfrom localflavor.us.forms import USStateField # Example: using a US-specific field\nfrom django.conf import settings\n\n# Minimal Django settings for standalone execution or in a Django project context\nif not settings.configured:\n    settings.configure(\n        INSTALLED_APPS=[\n            'localflavor', # Required for translations and some internal workings\n        ],\n        DEBUG=True,\n        SECRET_KEY=os.environ.get('DJANGO_SECRET_KEY', 'a-very-secret-key-for-testing-only'),\n        # Add other necessary settings like TEMPLATES, DATABASES for a full Django app\n    )\n\nclass MyUSForm(forms.Form):\n    state = USStateField()\n    city = forms.CharField(max_length=100)\n\n# Example usage (e.g., in a Django view or a test)\ndef process_form_data():\n    # Simulate form submission\n    form_data = {'state': 'NY', 'city': 'New York'}\n    form = MyUSForm(form_data)\n\n    if form.is_valid():\n        print(f\"Form is valid. State: {form.cleaned_data['state']}, City: {form.cleaned_data['city']}\")\n        return form.cleaned_data\n    else:\n        print(\"Form is not valid. Errors:\", form.errors)\n        return None\n\nif __name__ == '__main__':\n    print(\"Processing valid form data:\")\n    process_form_data()\n\n    print(\"\\nProcessing invalid form data:\")\n    invalid_form_data = {'state': 'XX', 'city': 'Invalid City'}\n    invalid_form = MyUSForm(invalid_form_data)\n    if not invalid_form.is_valid():\n        print(\"Form is not valid. Errors:\", invalid_form.errors)\n","lang":"python","description":"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."},"warnings":[{"fix":"Change all `from django.contrib.localflavor...` imports to `from localflavor...`. Install the standalone `django-localflavor` package.","message":"The `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>`.","severity":"breaking","affected_versions":"Django 1.5 and newer (for the 'django-localflavor' library, this affects all versions that depend on it being a separate package)."},{"fix":"Run your project's tests with `python -Wd` to display deprecation warnings and update code accordingly before upgrading to 3.0 or later.","message":"Version 3.0 removed all previously deprecated code. Ensure you have addressed all `DeprecationWarning` messages if upgrading from versions prior to 3.0.","severity":"breaking","affected_versions":"<3.0"},{"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.","message":"Specific 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.","severity":"breaking","affected_versions":"5.0 (LV, NP, NO), 4.0, 3.1 (MX, IN) and potentially future major versions."},{"fix":"Migrate any existing phone number fields to use `django-phonenumber-field` for better and more comprehensive support.","message":"django-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.","severity":"deprecated","affected_versions":"All versions (policy change, not a specific breaking version removal)."},{"fix":"Add `'localflavor'` to your `INSTALLED_APPS` list in `settings.py`.","message":"For localflavor's text (e.g., form field error messages) to be translated, `localflavor` must be included in your Django project's `INSTALLED_APPS` setting.","severity":"gotcha","affected_versions":"All versions."},{"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.","message":"Backwards-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.","severity":"gotcha","affected_versions":"All versions, as these reflect real-world changes."}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}