# django-localflavor keeps country specific form fields out of Django core

> django-localflavor is the Django Software Foundation package that carries the country and culture specific form fields once shipped as django.contrib.localflavor. It is small, permissively licensed and versioned alongside Django, but it is a legacy shape of validation and it has already dropped one of its features.

**django/django-localflavor** — Country-specific Django helpers, formerly of contrib fame

- Repository: https://github.com/django/django-localflavor
- Website: https://django-localflavor.readthedocs.io/
- Stars: 926 · Forks: 306
- Language: Python
- License: BSD-3-Clause
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/django-django-localflavor

## Split out of contrib in Django 1.5 to keep the framework core small

The idea behind django-localflavor is simple enough to state in one line: it offers additional functionality for particular countries or cultures. The README gives the examples that matter, form fields for your country's postal codes and for government ID numbers.
It used to be part of Django itself. The code lived in django.contrib.localflavor and was separated into a standalone package in Django 1.5 to keep the framework's core clean. That origin explains both the shape of the package and its licence. The project is published by the Django Software Foundation, the author field in pyproject.toml reads Django Software Foundation with the foundation@djangoproject.com address, and the licence is BSD-3-Clause.
The audience is Django developers whose forms have to accept data that is valid in one country and invalid in another. A date field, a choice field or a regex would be the wrong tool here because the rules differ by jurisdiction, and the whole point of a localflavor is that somebody already encoded them.
The package focuses on localized components, mainly form fields, and also includes generic date and IBAN/BIC form and model fields. Its documentation recommends adding `localflavor` to `INSTALLED_APPS` for migrations and translations.

## Two dependencies: Django itself and the python-stdnum validation library

The dependency list in pyproject.toml is short and tells you where the validation logic actually comes from.
```toml
[project]
name = "django-localflavor"
dynamic = ["version"]
requires-python = ">=3.9"
dependencies = [
    "django>=4.2",
    "python-stdnum>=2.2",
]
```
python-stdnum is the validation dependency, and django-localflavor is the Django shaped wrapper built on top of it rather than a second implementation of those rules.
The version is dynamic, read from localflavor.__version__ at build time, so the package version tracks the code rather than a hardcoded string. The build backend is setuptools with a requirement of setuptools >=77.0.3, and the project declares itself as type agnostic with an OS Independent classifier.
The supported Django versions are declared as classifiers rather than in a constraints file, and the list tells you the range.
```toml
classifiers = [
    "Development Status :: 5 - Production/Stable",
    "Framework :: Django",
    "Framework :: Django :: 4.2",
    "Framework :: Django :: 5.0",
    "Framework :: Django :: 5.1",
    "Framework :: Django :: 5.2",
]
```
The repository layout matches that simplicity: a single top level package directory named localflavor/, a docs/ directory, tests/, a tasks.py, a tox.ini and a.tx/ directory for translation work, plus the usual pyproject.toml and LICENSE.

## Getting the package and checking for deprecation warnings in your own code

The README does not print an install command, but it points to the two authoritative sources for obtaining the package: the Python Package Index at pypi.org/project/django-localflavor/ and the project documentation at django-localflavor.readthedocs.io, where the full list of available localflavors is published. Both are the places to look rather than a copy pasted line from an old tutorial.
The README also gives one command worth knowing, and it is not about installation. When you move between releases, it advises running your project's tests with the -W flag so that deprecation warnings appear and can be addressed.
```bash
python -Wd manage.py test
```
That advice comes from the 2.2 release notes, which state that all deprecated code will be removed in the 3.0 release and asks readers to run their tests using python -Wd so that deprecation warnings show up. For a package whose whole purpose is validation, a deprecation warning in the validation layer is exactly the kind of thing that silently changes what your form accepts.
The README also states plainly that you are encouraged to use the latest version of this package unless you need support for an unsupported version of Django. That framing tells you the compatibility matrix, not your preference, decides the version.

## Phone number fields were removed and the project points elsewhere

This is the sharpest edge in the package. The README states that django-localflavor no longer includes country specific phone number fields, and recommends the django-phonenumber-field package, which it describes as having excellent support for validating phone numbers in many countries. The link given is pypi.org/project/django-phonenumber-field/.
The reason for the removal is visible in the dependency list. This package depends on python-stdnum, and phone number validation is served by a dedicated project, and the README says that project does it well. Keeping a second implementation of the same validation inside a Django Software Foundation package would have meant maintaining two.
The practical consequence for an upgrade is that code importing a phone field from localflavor will fail, and the replacement is a different package with a different API rather than a renamed import. That is a migration, not an edit.
The same reasoning explains why this package stays small. It keeps the fields that are country specific and awkward to generalise, and hands the well served cases to packages that focus on them.

## Version numbers that break data, not just APIs

The release history in the README is unusual and worth reading carefully, because the version number is not simply the Django version.
```
**2026-08-01 - 5.1**: Django 4.2, 5.0, 5.1, 5.2 & 6.0

**2025-05-21 - 5.0**: Django 4.2, 5.0, 5.1 & 5.2

This release contains breaking data changes for the LV, NP and NO flavors.
```
Version 5.0, released on 2025-05-21, carries breaking data changes for the LV, NP and NO flavors, with a pointer to the changelog in the docs/changelog.rst file of the 5.0 branch. Version 3.1, released on 2021-05-28, carried breaking data changes for the MX and IN flavors. Version 3.0, released on 2020-02-19, removed all deprecated code and included a number of other breaking changes.
Note what breaking data changes means here. These are not renamed methods but changed validation rules or changed values, which is the kind of change that alters what your users are allowed to enter. A form that validated yesterday can reject a stored record today.
The remaining history lines up one to one with Django support windows: 4.0 for Django 3.2 to 4.2, 3.1 for Django 2.2 to 3.2, 3.0 for Django 2.2 and 3.0, 2.2 for Django 1.11 to 2.2, 2.1 for Django 1.11 to 2.1 and 2.0 for Django 1.11 to 2.0. The rule of thumb is that the package version tracks the range of Django versions it supports, so a Django upgrade usually means a localflavor upgrade too.

## Where localflavor is the wrong choice

There are three situations where reaching for this package is a mistake.
The first is general validation. If you need to check that a value is an integer in range, or that a date is in the past, localflavor has nothing for you. Its focus is localized helpers, though its generic package includes date and banking fields as well.
The second is phone numbers, already covered above. The fields are gone and the README redirects you.
The third is a project that needs to stay current on new Django releases. The package version is tied to the Django versions it supports, and the compatibility statement for the newest release, 5.1, covers Django 4.2, 5.0, 5.1, 5.2 and 6.0. There is no sign of a general purpose validation layer growing around the country modules.
On maintenance, the picture is calm rather than busy. The repository is not archived and the last push was on 2026-08-03, close to the 5.1 release on 2026-08-01. The repository itself has no GitHub releases, and the release history lives in the README instead, with the changelog served from the documentation site. The BSD-3-Clause licence is permissive, so using it inside a proprietary application carries few obligations beyond keeping the licence text.

## Conclusion

Adopt django-localflavor when you maintain a Django form that must accept a national postal code or a government identifier and you want the validation rules already written and tested. Do not adopt it for phone numbers, since those fields were removed in favour of django-phonenumber-field, and do not adopt it as a general validation framework, because its primary focus is localized helpers, although it also includes generic date and IBAN/BIC components and model fields. Before upgrading, read the changelog for the target release, since 5.0 carried breaking data changes for the LV, NP and NO flavors.

## FAQ

### What is django-localflavor used for?

It provides Django form fields with additional functionality for particular countries or cultures, for example form fields for your country's postal codes or government ID numbers. The code used to live in django.contrib.localflavor and was separated out in Django 1.5.

### Which Django versions does django-localflavor support?

The 5.1 release, dated 2026-08-01, covers Django 4.2, 5.0, 5.1, 5.2 and 6.0, and the pyproject.toml classifiers list Django 4.2 through 5.2. The package requires Python 3.9 or higher and django>=4.2.

### Does django-localflavor still provide phone number fields?

No. The README states that django-localflavor no longer includes country specific phone number fields and points to the django-phonenumber-field package, described as having excellent support for validating phone numbers in many countries.

### Are there breaking changes when upgrading django-localflavor?

Yes in some releases. The 5.0 release contains breaking data changes for the LV, NP and NO flavors, the 3.1 release contains breaking data changes for the MX and IN flavors, and the 3.0 release removed all deprecated code. The changelog in docs/changelog.rst has the details.

### What licence does django-localflavor use?

The pyproject.toml declares the licence as BSD-3-Clause with the licence text in the LICENSE file at the root of the repository. The project is published by the Django Software Foundation.

## Sources

- [django/django-localflavor on GitHub](https://github.com/django/django-localflavor)
- [Issues](https://github.com/django/django-localflavor/issues)
- [License: BSD-3-Clause](https://github.com/django/django-localflavor/blob/master/LICENSE)
- [Project website](https://django-localflavor.readthedocs.io/)
- [README](https://github.com/django/django-localflavor/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/django-django-localflavor