# django-phonenumber-field

> An international phone number field for django models.

- **URL**: https://www.freshcrate.ai/projects/django-phonenumber-field
- **Author**: pypi
- **Category**: Frameworks
- **Latest version**: `8.4.0` (2026-04-21)
- **License**: MIT
- **Source**: https://github.com/stefanfoulis/django-phonenumber-field/releases/
- **Homepage**: https://pypi.org/project/django-phonenumber-field/
- **Language**: Python
- **GitHub**: 1,550 stars, 322 forks
- **Registry**: pypi (`django-phonenumber-field`)
- **Tags**: `pypi`

## Description

========================
django-phonenumber-field
========================

.. image:: https://github.com/stefanfoulis/django-phonenumber-field/workflows/Test/badge.svg
    :target: https://github.com/stefanfoulis/django-phonenumber-field/workflows/Test/badge.svg
.. image:: https://img.shields.io/coveralls/stefanfoulis/django-phonenumber-field/develop.svg
    :target: https://coveralls.io/github/stefanfoulis/django-phonenumber-field?branch=main

A Django library which interfaces with `python-phonenumbers`_ to validate, pretty print and convert
phone numbers. ``python-phonenumbers`` is a port of Google's `libphonenumber`_ library, which
powers Android's phone number handling.

.. _`python-phonenumbers`: https://github.com/daviddrysdale/python-phonenumbers
.. _`libphonenumber`: https://github.com/google/libphonenumber

Documentation
=============

https://django-phonenumber-field.readthedocs.io/

Running tests
=============

tox needs to be installed. To run the whole test matrix with the locally
available Python interpreters and generate a combined coverage report::

    tox

run a specific combination::

    tox -e py310-djmain,py39-djmain

## Recent releases

| Version | Date | Urgency | Changes |
| --- | --- | --- | --- |
| `8.4.0` | 2026-04-21 | Low | Imported from PyPI (8.4.0) |
| `8.3.0` | 2025-10-06 | Low | ## What's Changed * Allow configuring `empty_value` and `max_length` for `SplitPhoneNumberField` by @ilkkao in https://github.com/stefanfoulis/django-phonenumber-field/pull/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`  ## New Contributors * @ilkkao made their first contribution in https://github.com |
| `8.2.0` | 2025-10-02 | Low | ## What's Changed * Fix lost region when `PHONENUMBER_DEFAULT_FORMAT` is `NATIONAL` by @bblanchon in https://github.com/stefanfoulis/django-phonenumber-field/pull/636 * Bump actions/setup-python from 5 to 6 by @dependabot[bot] in https://github.com/stefanfoulis/django-phonenumber-field/pull/642 * Fix translations by @interDist in https://github.com/stefanfoulis/django-phonenumber-field/pull/641 * Add Hungarian locale by @karolyi in https://github.com/stefanfoulis/django-phonenumber-field/pul |
| `8.1.0` | 2025-04-10 | Low | ## What's Changed * Remove non-geo phone numbers from the SplitPhoneNumberWidget by @francoisfreitag in https://github.com/stefanfoulis/django-phonenumber-field/pull/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 Inte |
| `8.0.0` | 2024-06-24 | Low | ## What's Changed  ### Breaking changes  * Remove `PhoneNumberInternationalFallbackWidget` by @francoisfreitag in https://github.com/stefanfoulis/django-phonenumber-field/pull/602    Use `phonenumber_field.widgets.RegionalPhoneNumberWidget` instead.  * Move validation from widgets to the form fields by @francoisfreitag in https://github.com/stefanfoulis/django-phonenumber-field/pull/603    Previously, the widgets were validating the phone number, leaving no room for the [django regular |
| `7.3.0` | 2023-12-29 | Low | ## What's Changed * Add support for Django 5.0 by @adamchainz in https://github.com/stefanfoulis/django-phonenumber-field/pull/582 * Document phone number extension handling by @francoisfreitag in https://github.com/stefanfoulis/django-phonenumber-field/pull/583 * Make PhoneNumberPrefixSelect use the provided region by @francoisfreitag in https://github.com/stefanfoulis/django-phonenumber-field/pull/593 * Update Italian locale by @RuggeroFabbiano in https://github.com/stefanfoulis/django-pho |
| `7.2.0` | 2023-10-05 | Low | *This release should have been an 8.0 by the semver, as the DB converter for the model field can break working code.*  ## What's Changed * **BREAKING**: Add a DB converter for the model field, fixing `values_list()` of `PhoneNumberField`s by @francoisfreitag in https://github.com/stefanfoulis/django-phonenumber-field/pull/559 * Use public attributes and methods from phonenumbers by @francoisfreitag in https://github.com/stefanfoulis/django-phonenumber-field/pull/535  * Remove zip_safe flag |
| `7.1.0` | 2023-04-26 | Low | ## What's Changed * Update Norwegian translations by @ddabble in https://github.com/stefanfoulis/django-phonenumber-field/pull/549 * Drop support for Django 4.0, add Django 4.2 by @francoisfreitag in https://github.com/stefanfoulis/django-phonenumber-field/pull/550  ### Miscellaneous * Update python and Django matrix by @francoisfreitag in https://github.com/stefanfoulis/django-phonenumber-field/pull/548 * Add common virtualenv locations to flake8 exclude and .gitignore by @blaedd in https |
| `7.0.2` | 2023-01-09 | Low | ## What's Changed * Updated Swedish translations by @tjwalch in https://github.com/stefanfoulis/django-phonenumber-field/pull/544  ## New Contributors * @tjwalch made their first contribution in https://github.com/stefanfoulis/django-phonenumber-field/pull/544  **Full Changelog**: https://github.com/stefanfoulis/django-phonenumber-field/compare/7.0.1...7.0.2 |
| `7.0.1` | 2022-12-06 | Low | ## What's Changed * Allow multiple DRF is_valid calls to succeed by @phillipuniverse in https://github.com/stefanfoulis/django-phonenumber-field/pull/543  ## New Contributors * @phillipuniverse made their first contribution 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 |

## Citation

- HTML: https://www.freshcrate.ai/projects/django-phonenumber-field
- Markdown: https://www.freshcrate.ai/projects/django-phonenumber-field.md
- Dependencies JSON: https://www.freshcrate.ai/api/projects/django-phonenumber-field/deps

_Generated by freshcrate.ai. Indexes pypi releases for AI-agent ecosystem packages._