daviddrysdale

python-phonenumbers: Parse and Format Phone Numbers with Google's libphonenumber

python-phonenumbers is a Python port of Google's libphonenumber for parsing, validating, formatting, and finding information about phone numbers. It supports Python 2.5–2.7 and Python 3.x, with optional geocoding, carrier, and timezone metadata.

View on GitHub Compare
Stars
3.8k
Forks
446
Stars, last 30 days
+6
Last commit
7 days ago
Contributors
31

Our take

Activeregular commits

Health score

35/100

How it is scored
Activity
37
Community
35
Issues
32
Pull requests
35

+6 stars in the last 30 days

  • Slower to close issues than 96% of the projects we track

This is an established, actively committed Python port of Google's libphonenumber, but recent development is highly concentrated in one contributor and the project has had no release in over a year.

Good fit if

  • You need libphonenumber-style parsing, validation, and formatting from Python.
  • You can work with its region-dependent parsing rules and choose whether to load extended metadata.
  • You are comfortable reviewing ongoing development activity and using the Apache-2.0-licensed code.

Look elsewhere if

  • Your application needs a recently published release as evidence of current packaged updates.
  • You need phone-number metadata features that are not provided by this library or its optional packages.
  • Your project cannot accept the maintenance concentration reflected in recent contributor activity.
All health signals
Last commit2026-11-06 (7 days ago)
Commits, last 90 days24
Releases, last 12 months0
Contributors31 (top contributor: 97% of commits)
Issues closed, last 90 days4 (typically closed in 535 days)
Pull requests merged, last 90 days4 (typically merged in 2 days)
Project age15 years

Checked on 2026-11-14 with the GitHub API.

Project history

Daily GitHub snapshots since Oct 7, 2026. History covers stars and forks; health signals are not tracked historically.

Selected snapshot

Stars

3,782

Forks

447

Change since Nov 17, 2026: 0 stars·0 forks

Overview

python-phonenumbers is a Python port of Google's libphonenumber, designed to help applications interpret phone-number input consistently across regions. It parses numbers using a region when needed, distinguishes possible numbers from valid ones, and formats them for display or standardized output.

The library also supports matching numbers in text and, with separate metadata packages, looking up location, carrier, and timezone information. The README describes support for Python 2.5–2.7 and Python 3.x in the same codebase.

Key Features

  • Parse numbers from international formats or with a default dialing region.
  • Check whether a number is possible or valid according to numbering-plan metadata.
  • Format numbers in national, international, and E.164 formats.
  • Apply formatting as a user types with AsYouTypeFormatter.
  • Find phone numbers in text and retrieve their positions in the original string.
  • Look up geographic descriptions, original carrier information, and possible timezones using optional metadata packages.
  • Load core region metadata on demand, with a phonenumberslite option that omits extended metadata.
  • Provide type stubs for static type checking on Python 3.

Use Cases

  • Application developers validating phone numbers entered in registration or contact forms.
  • Teams normalizing stored numbers for display or exchange in E.164 format.
  • Messaging or customer-support tools extracting phone numbers from user-provided text.
  • Interfaces that need to format a number while someone types it.
  • Applications that need approximate location, carrier, or timezone details where the library's metadata supports them.

What you need

Detected in the repository

  • Python (main language on GitHub)
  • Automated checks on GitHub Actions

License in plain words

Apache-2.0permissive

  • Commercial use: yes
  • Modify and redistribute: yes
  • You must keep: the license, the NOTICE file and a note of your changes
  • Share your changes: no
  • Includes an explicit patent grant from the contributors:

A summary, not legal advice: the LICENSE file is what applies.

Getting Started

Install the package with pip:

pip install phonenumbers

See the README and documentation for parsing options and additional functionality.

Considerations

  • Phone-number parsing is region-sensitive: inputs without an international prefix generally need a default region, and parsing alone does not establish that a number is valid.
  • The core and extended metadata add memory overhead. Geocoding, carrier, and timezone data are separate; the README describes phonenumberslite as an option without those packages.
  • The project is marked active and has recent commits, but most of the code comes from one person. Issue resolution has also been slow by the measured median, so assess whether the maintenance pattern suits your needs.
  • There have been no releases in over a year, so check the repository and release history when you need to verify the availability of particular metadata updates.
  • The project is licensed under Apache-2.0; review that license against your distribution requirements.

Found this useful?

Share it with someone who would like python-phonenumbers.