NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI · #1505 most downloaded on PyPI
An international phone number field for django models.
Last release 2 months ago
23 Jul 2026
Ships fairly regularly
a new release about every 4 months
Most releases are documented
notes for 33 of 39 stable releases
Nothing withdrawn
no release was ever pulled
15 years old
41 releases · first in 2011
Fix strip parameter by @xi in #676
Full Changelog: 8.4.0...8.5.0
One column per quarter.
Handle empty values in SplitPhoneNumberField with max_length by @SupImDos in #652
SplitPhoneNumberField with max_length by @SupImDos in #652Full Changelog: 8.3.0...8.4.0
Allow configuring empty_value and max_length for SplitPhoneNumberField by @ilkkao in #632
Allow configuring empty_value and max_length for SplitPhoneNumberField by @ilkkao in #632
Mimics django CharField behavior more closely:
- empty_value offers controls over the normalization (typically, the empty str "" or None)
- max_length allows using the form field with forms_for_model
Full Changelog: 8.2.0...8.3.0
Fix lost region when PHONENUMBER_DEFAULT_FORMAT is NATIONAL by @bblanchon in #636
PHONENUMBER_DEFAULT_FORMAT is NATIONAL by @bblanchon in #636Full Changelog: 8.1.0...8.2.0
Remove non-geo phone numbers from the SplitPhoneNumberWidget by @francoisfreitag in #614
Remove non-geo phone numbers from the SplitPhoneNumberWidget by @francoisfreitag in #614
The phone number prefix field allows to select a world region, and maps to its prefix (e.g. get +33 for France). It was incorrectly offering regions reserved for very specific use and which cannot be mapped to a world region. Example prefixes include 800 (Universal International Freephone Service), 808 (Universal International Shared Cost Number), 870 (Global Mobile Satellite System), and others.
If such a prefix was selected, the field would plainly crash. Since the prefix purpose is to let users select a world region, prevent from selecting non-geo options in the prefix list. Please open an issue if you would like to see this use case supported.
Document how to customize SplitPhoneNumberField fields by @francoisfreitag in #631
Clarify translations context for error messages by @francoisfreitag in #613
Full Changelog: 8.0.0...8.1.0
Remove PhoneNumberInternationalFallbackWidget by @francoisfreitag in #602
Remove PhoneNumberInternationalFallbackWidget by @francoisfreitag in #602
Use phonenumber_field.widgets.RegionalPhoneNumberWidget instead.
Move validation from widgets to the form fields by @francoisfreitag in #603
Previously, the widgets were validating the phone number, leaving no room for the django regular validation procedure. If you performed custom validation on PhoneNumberFields, see the migration guide below.
Full Changelog: 7.3.0...8.0.0
Previously, the widgets handled part of the validation. That behavior prevents overriding validation in form fields, as widgets were casting the value into a PhoneNumber object, validating it in the process.
Following the MultiValueField implementation from Django (and MultiWidget), the widget now handles the presentation logic, but makes
no attempt at validation. The new SplitPhoneNumberField handles the logic of validating the region choice and the number, and the PhoneNumberPrefixWidget simply dispatches the region and number data to the appropriate widget.
In order to retain backward compatibility, now that the validate_international_phonenumber actually comes into play, its error code has been changed to invalid, so that the custom error message for invalid shows.
validate_international_phonenumberReview uses of the invalid_phone_number error code. You’ll probably want to replace them with invalid. Given that the validator usually did not come into play, you shouldn’t find many uses.
PhoneNumberField with RegionalPhoneNumberWidgetMove the custom validation occurs in the Django Form clean_FIELD() (or clean()), and no changes should be noticeable.
PhoneNumberField with PhoneNumberPrefixWidgetUse the SplitPhoneNumberField instead. Error messages will change slightly and should be more precise (whether the region is not part of
the choices, or the number cannot be interpreted in the selected region).
For more examples, take a look at tests.test_formfields.SplitPhoneNumberFieldTest.
Make sure GitHub loads the diff for file tests/test_formfields.py
The following tests should cover most use cases:
Add support for Django 5.0 by @adamchainz in #582
Full Changelog: 7.2.0...7.3.0
This release should have been an 8.0 by the semver, as the DB converter for the model field can break working code.
This release should have been an 8.0 by the semver, as the DB converter for the model field can break working code.
BREAKING: Add a DB converter for the model field, fixing values_list() of PhoneNumberFields by @francoisfreitag in #559
Use public attributes and methods from phonenumbers by @francoisfreitag in #535
Remove zip_safe flag from setup.cfg by @francoisfreitag in #553
feat: Add mypy to CI by @last-partizan in #563
Drop support for Python 3.7 by @francoisfreitag in #561
Show support for Python 3.11 by @francoisfreitag in #570
Add support for Python 3.12 by @francoisfreitag in #576
Full Changelog: 7.1.0...7.2.0
Update Norwegian translations by @ddabble in #549
Full Changelog: 7.0.2...7.1.0
Updated Swedish translations by @tjwalch in #544
Allow multiple DRF is_valid calls to succeed by @phillipuniverse in https://github.com/stefanfoulis/django-phonenumber-field/pull/543
Full Changelog: https://github.com/stefanfoulis/django-phonenumber-field/compare/7.0.0...7.0.1
PhoneNumberInternationalFallbackWidget will be replaced by RegionalPhoneNumberWidget in the next major version. It is deprecated until the next major…
RegionalPhoneNumberWidget becomes the default widget for the formfields.PhoneNumberField.formfields.PhoneNumberField no longer sets the input_type attribute of its widget to tel. That behavior did not make sense for the existing PhoneNumberPrefixWidget and was dropped.PhoneNumberInternationalFallbackWidget will be replaced by RegionalPhoneNumberWidget in the next major version. It is deprecated until the next major release.Restore PhoneNumberPrefixWidget number input on form errors by @francoisfreitag in https://github.com/stefanfoulis/django-phonenumber-field/pull/520
Fixes a bug where the form field prepare_value() transformed the PhoneNumber value to an str in the national format, but PhoneNumberPrefixWidget expects its value to be a PhoneNumber. formfields.PhoneNumberField now represents its value with a PhoneNumber object, giving widgets more control on how to display the value.
That behavior prompted the change to PhoneNumberInternationalFallbackWidget becoming the default widget, to preserve the behavior established in https://github.com/stefanfoulis/django-phonenumber-field/commit/005769cf39323e5b23710783f45befb546672cd6. Switching to the widget allows users to opt-out from that behavior (e.g. by using a TextInput widget), whereas prepare_value() forced the conversion to the national string format.
Set PhoneNumberInternationalFallbackWidget input_type to tel by @francoisfreitag in https://github.com/stefanfoulis/django-phonenumber-field/pull/521
Previously, the <input> from the PhoneNumberInternationalFallbackWidget was set to text.
Evolve PhoneNumberInternationalWidget to RegionalPhoneNumberWidget by @francoisfreitag in https://github.com/stefanfoulis/django-phonenumber-field/pull/529
The newer widget gives more control over the display of phone numbers. The behavior of PhoneNumberInternaltionalWidget can be retained by setting PHONENUMBER_DEFAULT_FORMAT="INTERNATIONAL", which is why PhoneNumberInternaltionalWidget will be removed in the next major version.
Add Dutch translation by @thijskramer in https://github.com/stefanfoulis/django-phonenumber-field/pull/532
Add documentation and host it at readthedocs.org by @francoisfreitag in https://github.com/stefanfoulis/django-phonenumber-field/pull/531
Prefer SUPPORTED_REGIONS over _AVAILABLE_REGION_CODES by @francoisfreitag in https://github.com/stefanfoulis/django-phonenumber-field/pull/528
Full Changelog: https://github.com/stefanfoulis/django-phonenumber-field/compare/6.4.0...7.0.0
Allow restricting PhoneNumberPrefixWidget country choices by @francoisfreitag in https://github.com/stefanfoulis/django-phonenumber-field/pull/525
Full Changelog: https://github.com/stefanfoulis/django-phonenumber-field/compare/6.3.0...6.4.0
Accept per-widget attrs for PhoneNumberPrefixWidget by @francoisfreitag in https://github.com/stefanfoulis/django-phonenumber-field/pull/502
Full Changelog: https://github.com/stefanfoulis/django-phonenumber-field/compare/6.2.0...6.3.0
PhoneNumberPrefixWidget improvement for regions sharing same country prefix by @amateja in https://github.com/stefanfoulis/django-phonenumber-field/pu
PhoneNumberPrefixWidget improvement for regions sharing same country prefix by @amateja in https://github.com/stefanfoulis/django-phonenumber-field/pull/493maxlength attribute for html5 compliance by @sterliakov in https://github.com/stefanfoulis/django-phonenumber-field/pull/490Full Changelog: https://github.com/stefanfoulis/django-phonenumber-field/compare/6.1.0...6.2.0
Make formfields.PhoneNumberField honor PHONENUMBER_DEFAULT_REGION by @francoisfreitag in https://github.com/stefanfoulis/django-phonenumber-field/pull
formfields.PhoneNumberField honor PHONENUMBER_DEFAULT_REGION by @francoisfreitag in https://github.com/stefanfoulis/django-phonenumber-field/pull/476PhoneNumber.__repr__ by @francoisfreitag in https://github.com/stefanfoulis/django-phonenumber-field/pull/485Full Changelog: https://github.com/stefanfoulis/django-phonenumber-field/compare/6.0.0...6.1.0
Make formfields.PhoneNumberField honor PHONENUMBER_DEFAULT_REGION
Use PHONENUMBER_DEFAULT_REGION for example phone number in form field errors.
Add support for Django 4.0
Add Persian (farsi) translations.
Update uk_AR translations
Backwards incompatible changes
Drop support for Python 3.6
Update Czech, Dutch and pt_BR translations
Backwards incompatible changes
formfields.PhoneNumberField with a region now display national phone
numbers in the national format instead of PHONENUMBER_DEFAULT_FORMAT.
International numbers are displayed in the PHONENUMBER_DEFAULT_FORMAT.Full Changelog: https://github.com/stefanfoulis/django-phonenumber-field/compare/5.2.0...6.0.0
Lazy load formfields.PhoneNumberField translation for invalid data.
Lazy load formfields.PhoneNumberField translation for invalid data.
Update Russian translations
Backwards incompatible changes
Drop support for end-of-life Django 3.0
Allow sorting PhoneNumber\ s from Python
Allow sorting PhoneNumbers from Python
Add support for Python 3.9 and Django 3.2
Add Argentinian, Bulgarian, Indonesian, Ukrainian translations
Update Esperanto and European Spanish translations
Backwards incompatible changes
Drop support for Python 3.5
Fix rendering PhonePrefixSelect with initial passed to the constructor.
Add support for Django 3.1.
Fix rendering PhonePrefixSelect with initial passed to the constructor.
The Babel dependency is now optional.
Switched to setuptools declarative configuration for packaging and installation.
Add Arabic and Russian translation.
Correct License information in package metadata.
Backwards incompatible changes
Drop support for end-of-life Django 1.11 and 2.1.
As the Babel dependency is now optional, you must now install it to use PhoneNumberPrefixWidget. If you do not install it, an ImproperlyConfigured exception will be raised when instantiated.
The big version bump is due to the change in how invalid phone numbers are handled. Starting with 2.4.0 we added very aggressive validation, which rai
The big version bump is due to the change in how invalid phone numbers are handled. Starting with 2.4.0 we added very aggressive validation, which raised ValueError for invalid numbers. This caused problems in unexpected places (like when filtering a queryset). Starting with 4.0.0 we acknowledge that we can not completely prevent invalid numbers from entering the system. Changes directly to the database, validation changes in the upstream phonenumbers library, changes in the django settings may all lead to invalid numbers in the database. Now it is possible to save an invalid number to the database and __str__ and __repr__ clearly indicate invalid numbers.
Don’t raise ValueError on invalid phone numbers - __str__ and __repr__ updated to report invalid phone numbers correctly if detected.
Various translation updates
Allow overriding the default invalid phone number message.
Allow overriding the default invalid phone number message.
Update French and Hebrew translations.
Update French and Hebrew translations.
Add a valid phone number example to invalid phone number error messages.
Backwards incompatible changes
Drop support for Django 2.0.
Drop support for Python 2.7 and 3.4.
A PhoneNumberField can now be deferred with QuerySet.defer().
A PhoneNumberField can now be deferred with QuerySet.defer().
Saving or filtering by an invalid phone number will now raise a ValueError.
The model field attribute PhoneNumberField.region now uses PHONENUMBER_DEFAULT_REGION if not specified.
Fixed a regression to re-allow the model field to override the default form field.
Fixed a regression to re-allow the model field to override the default form field.
Added the region keyword argument to PhoneNumberField.
Added the region keyword argument to PhoneNumberField.
Fix representation of invalid phone numbers in the database, previously stored as +NoneNone. Now, invalid phone numbers are represented as:
Existing database records can be upgraded with a data migration.
Added support for Django 2.2.
Tests are now included in the sdist package.
modelfields.PhoneNumberField now inherits from models.CharField instead of models.Field.
* Added support for null=True
Added support for null=True
Removed hardcoded dependency to phonenumbers library. Now developers have to manually install either phonenumbers or phonenumberslite.
Removed hardcoded dependency to phonenumbers library. Now developers have to manually install either phonenumbers or phonenumberslite.
Added Romanian locale
Added Bangla locale
Update French locale
Update Italian locale
Statically depend on phonenumbers Previously the phonenumberslight dependency was used dynamically in setup.py if it already was installed, causing pr
Statically depend on phonenumbers Previously the phonenumberslight dependency was used dynamically in setup.py if it already was installed, causing problems with building wheels and with pipenv.
Added Ukrainian locale
Added Simplified Chinese locale
* Add Django 2.0 support * Drop Support for Django<1.11 * Translations: Swedish
Add Django 2.0 support
Drop Support for Django<1.11
Translations: Swedish
Various bugfixes and improvements
Add rest_framework Serializer
Hashable phonenumber object
Various bugfixes and improvements
Translations: Brazilian Portuguese, Spanish, Norwegian, Dutch, Azerbaijani, Turkish and French
Django 1.10 support
Bugfixes and cleanup
Translations: Brazilian Portuguese, Spanish, Norwegian, Dutch, Azerbaijani, Turkish and French
support for HTML5.0 tel input type added
Django 1.9 support
README updated and links fixed
support for HTML5.0 tel input type added
locale files are now included
new translations: Danish, Esperanto, Polish, all translations reformatted, Russian translation expanded
PhoneNumberField.get_prep_value changed to enable setting null=True
new widget added: PhoneNumberInternationalFallbackWidget
new backward compatible requirement phonenumberslite instead of phonenumbers
lots of tests
dropped support for PHONENUMER_DEFAULT_REGION setting with typo
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Your coding agent can read these notes before it upgrades. Set up the MCP server →