Python-phonenumbers

raw JSON →
9.0.26 verified Tue May 12 auth: no python install: verified

Python-phonenumbers is a Python port of Google's `libphonenumber` library, providing robust functionality for parsing, formatting, storing, and validating international phone numbers. It is actively maintained and regularly updated to reflect upstream changes from the original Java library. The current version is 9.0.26.

pip install phonenumbers

Common errors

error ModuleNotFoundError: No module named 'phonenumbers' ↓
cause The `phonenumbers` library is not installed in the Python environment being used, or there is a mismatch between the installed package name and the import statement.
fix
Ensure the library is correctly installed using pip: pip install phonenumbers. If using a virtual environment, ensure it's activated before installation. Verify the import statement is import phonenumbers.
error phonenumbers.phonenumberutil.NumberParseException: (0) Missing or invalid default region. ↓
cause The `parse()` function was called with a national phone number string but without specifying a valid default region code, or with an invalid region code, making it impossible for the library to interpret the number's format.
fix
When parsing a national number (without an international dialing code), provide the two-letter ISO 3166-1 alpha-2 country code as the second argument to phonenumbers.parse(). For international numbers (starting with '+'), the region code can often be None. Example: phonenumbers.parse('0721234567', 'RO') or phonenumbers.parse('+40721234567', None).
error phonenumbers.phonenumberutil.NumberParseException: (1) The string supplied did not seem to be a phone number. ↓
cause The input string provided to the `parse()` function does not resemble a valid phone number, contains too few digits, or includes unexpected characters, preventing the library from recognizing it as a parseable number.
fix
Ensure the input string is a plausible phone number. This error indicates fundamental parsing failure, often requiring pre-validation of user input or a robust try-except block to handle malformed strings gracefully. Example: try: number = phonenumbers.parse(input_string, 'US') except phonenumbers.phonenumberutil.NumberParseException: print('Invalid number format').
error AttributeError: 'str' object has no attribute 'italian_leading_zero' ↓
cause A function that expects a `PhoneNumber` object (returned by `phonenumbers.parse()`) was instead passed a string. This often happens after `phonenumbers.format_number()` is called, as `format_number` returns a string, not a `PhoneNumber` object.
fix
Ensure that subsequent operations requiring a PhoneNumber object receive the parsed object, not the formatted string. If you need to re-validate or operate on a formatted number, parse it again into a PhoneNumber object. Example: parsed_number = phonenumbers.parse('+15551234567', 'US'); formatted_string = phonenumbers.format_number(parsed_number, phonenumbers.PhoneNumberFormat.E164); # If you need to validate formatted_string, you must re-parse it: re_parsed_number = phonenumbers.parse(formatted_string, None); is_valid = phonenumbers.is_valid_number(re_parsed_number).

Warnings

gotcha Calling `phonenumbers.parse()` with a non-E.164 number and `None` as the default region will raise a `NumberParseException`. ↓
fix Always provide a valid default region code (e.g., 'US', 'GB') when parsing numbers that are not in E.164 international format (starting with '+') or wrap parsing calls in a `try-except phonenumbers.NumberParseException` block.
breaking In version 8.0.0, methods like `_for_region` in `shortnumberinfo.py` no longer accept strings; they now require a `PhoneNumber` object. ↓
fix If migrating from versions prior to 8.0.0, ensure that you call `phonenumbers.parse()` first to create a `PhoneNumber` object and pass that object to these methods.
gotcha The `PhoneNumberMatcher` class, used for extracting phone numbers from text, is explicitly stated as not being thread-safe. ↓
fix Do not share `PhoneNumberMatcher` instances across multiple threads. Create a new instance for each thread or use appropriate locking mechanisms if sharing is unavoidable.
gotcha The full `phonenumbers` library includes substantial metadata (e.g., geocoder, carrier, timezone data) which can impact memory footprint, especially in resource-constrained environments. ↓
fix If memory usage is a critical concern, consider using the `phonenumberslite` variant (`pip install phonenumberslite`), which omits some of the larger metadata packages. Alternatively, be aware of the memory implications and manage them for your application.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk
3.10 alpine (musl) wheel - 0.07s 100.7M
3.10 alpine (musl) - - 0.07s 99.9M
3.10 slim (glibc) wheel 4.4s 0.04s 101M
3.10 slim (glibc) - - 0.04s 100M
3.11 alpine (musl) wheel - 0.19s 67.4M
3.11 alpine (musl) - - 0.21s 67.0M
3.11 slim (glibc) wheel 4.5s 0.16s 68M
3.11 slim (glibc) - - 0.15s 68M
3.12 alpine (musl) wheel - 0.11s 56.7M
3.12 alpine (musl) - - 0.12s 56.4M
3.12 slim (glibc) wheel 4.7s 0.13s 57M
3.12 slim (glibc) - - 0.12s 57M
3.13 alpine (musl) wheel - 0.10s 56.5M
3.13 alpine (musl) - - 0.12s 56.0M
3.13 slim (glibc) wheel 4.6s 0.11s 57M
3.13 slim (glibc) - - 0.12s 57M
3.9 alpine (musl) wheel - 0.06s 50.6M
3.9 alpine (musl) - - 0.07s 50.4M
3.9 slim (glibc) wheel 5.4s 0.04s 51M
3.9 slim (glibc) - - 0.05s 51M

Imports

Quickstart last tested: 2026-04-24

This quickstart demonstrates how to parse, validate, format, and retrieve auxiliary information (carrier, region, timezone) for a phone number. It handles potential parsing errors using a try-except block.

import phonenumbers
from phonenumbers import geocoder, carrier, timezone, PhoneNumberFormat

# 1. Parse a phone number
#   - The second argument ('GB') provides a default region if the number is not in E.164 format.
#   - If the number is E.164 (e.g., '+44...'), None can be used as the default region.
phone_number_str = "+442083661177"
country_code = "GB" # Default region for parsing, if number is not in international format

try:
    parsed_number = phonenumbers.parse(phone_number_str, country_code)
    print(f"Parsed Number: {parsed_number}")

    # 2. Validate the phone number
    is_valid = phonenumbers.is_valid_number(parsed_number)
    is_possible = phonenumbers.is_possible_number(parsed_number)
    print(f"Is Valid: {is_valid}, Is Possible: {is_possible}")

    if is_valid:
        # 3. Format the phone number in various ways
        national_format = phonenumbers.format_number(parsed_number, PhoneNumberFormat.NATIONAL)
        international_format = phonenumbers.format_number(parsed_number, PhoneNumberFormat.INTERNATIONAL)
        e164_format = phonenumbers.format_number(parsed_number, PhoneNumberFormat.E164)

        print(f"National Format: {national_format}")
        print(f"International Format: {international_format}")
        print(f"E.164 Format: {e164_format}")

        # 4. Get carrier, region, and timezone information
        #    Note: These lookups depend on the data included in the phonenumbers library.
        carrier_name = carrier.name_for_number(parsed_number, "en")
        region_description = geocoder.description_for_number(parsed_number, "en")
        timezones = timezone.time_zones_for_number(parsed_number)

        print(f"Carrier: {carrier_name}")
        print(f"Region: {region_description}")
        print(f"Timezones: {timezones}")

except phonenumbers.NumberParseException as e:
    print(f"Error parsing number: {e}")
last verified Tue May 12
next check Sat Jun 27