Phonenumbers Lite

9.0.27 · active · verified Fri Apr 10

Phonenumberslite is a Python port of Google's `libphonenumber` library, designed for parsing, formatting, storing, and validating international phone numbers. It is a 'lite' version of the main `phonenumbers` library, specifically omitting the larger geocoding, carrier, and timezone data packages to reduce its footprint, making it suitable for environments with memory or space limitations. The library is actively maintained, with the current version being 9.0.27.

Warnings

gotcha The 'phonenumberslite' package explicitly excludes geocoding, carrier, and timezone data to reduce its size. If you need these functionalities (e.g., `phonenumbers.geocoder`, `phonenumbers.carrier`, `phonenumbers.timezone`), you must install the full `phonenumbers` package instead.
Fix: If geocoding, carrier, or timezone features are required, `pip uninstall phonenumberslite` and then `pip install phonenumbers`.
gotcha The `phonenumbers.parse()` function requires a `region_code` argument (e.g., 'US', 'GB') unless the input phone number is in E.164 format (starts with '+'). If a non-E.164 number is passed without a `region_code`, a `NumberParseException` will be raised.
Fix: Always provide a `region_code` (e.g., `phonenumbers.parse('02083661177', 'GB')`) for numbers not in E.164 format, or handle `NumberParseException` appropriately.
gotcha Validation of a phone number can be done with `is_possible_number()` or `is_valid_number()`. `is_possible_number()` performs a quick length-based check and is faster, while `is_valid_number()` performs a more thorough validation including prefix and region checks. For strict validation, always use `is_valid_number()`.
Fix: Use `phonenumbers.is_valid_number(parsed_number)` for comprehensive validation. Use `is_possible_number()` for a quicker, less strict check when performance is critical (e.g., filtering a large dataset).
gotcha The `phonenumbers` library's `PhoneNumber` objects are typically immutable and should be created using the `phonenumbers.parse()` function. Direct instantiation of `PhoneNumber` objects is not the recommended or supported way to work with the library.
Fix: Always use `phonenumbers.parse(number_string, region_code)` to obtain a `PhoneNumber` object.

Install

pip install phonenumberslite Install with pip

Imports

phonenumbers
```
import phonenumbers
```
The primary module for all core functionality.
PhoneNumberFormat
```
from phonenumbers import PhoneNumberFormat
```
Used to specify formatting options for phone numbers.
geocoder
The 'phonenumberslite' version *does not include* geocoding, carrier, or timezone functionality to reduce package size. Attempting to import these will fail or result in missing attributes. Use the full 'phonenumbers' package for these features.

Quickstart

This quickstart demonstrates how to parse, validate, and format phone numbers using `phonenumberslite`. It shows how to handle numbers with and without explicit region codes, checks for validity and possibility, and formats numbers into E.164, International, and National formats. It also includes error handling for `NumberParseException` when an invalid string is provided.

import phonenumbers
from phonenumbers import PhoneNumberFormat
from phonenumbers.phonenumberutil import NumberParseException

# Parse a phone number
try:
    # Example with explicit region code for a non-E.164 number
    number_str_gb = "020 7946 0958"
    parsed_number_gb = phonenumbers.parse(number_str_gb, "GB")
    print(f"Parsed GB Number: {parsed_number_gb}")

    # Example with E.164 format (no region needed)
    number_str_e164 = "+15555551234"
    parsed_number_e164 = phonenumbers.parse(number_str_e164, None)
    print(f"Parsed E164 Number: {parsed_number_e164}")

    # Validate the number
    is_valid = phonenumbers.is_valid_number(parsed_number_gb)
    is_possible = phonenumbers.is_possible_number(parsed_number_gb)
    print(f"Is GB number valid? {is_valid}")
    print(f"Is GB number possible? {is_possible}")

    # Format the number
    formatted_e164 = phonenumbers.format_number(parsed_number_gb, PhoneNumberFormat.E164)
    formatted_international = phonenumbers.format_number(parsed_number_gb, PhoneNumberFormat.INTERNATIONAL)
    formatted_national = phonenumbers.format_number(parsed_number_gb, PhoneNumberFormat.NATIONAL)
    
    print(f"Formatted E.164: {formatted_e164}")
    print(f"Formatted International: {formatted_international}")
    print(f"Formatted National: {formatted_national}")

    # Attempt to parse an invalid number
    invalid_number_str = "not a phone number"
    phonenumbers.parse(invalid_number_str, "US")

except NumberParseException as e:
    print(f"Error parsing number: {e.args[0]}")

view raw JSON →