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.
Install & Compatibility
Where this runs
tested against v9.0.32 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.925 runs
installs and imports cleanly · install 0.0s · import 0.106s · 99.9MB
glibcpy 3.10–3.925 runs
installs and imports cleanly · install 4.7s · import 0.096s · 101MB
67MB installed
● package 67MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
phonenumbers
✓ import phonenumbers
parse
✓ import phonenumbers
parsed_number = phonenumbers.parse("+12133734253", "US")
format_number
✓ from phonenumbers import PhoneNumberFormat
formatted_number = phonenumbers.format_number(number_obj, PhoneNumberFormat.INTERNATIONAL)
is_valid_number
✓ is_valid = phonenumbers.is_valid_number(number_obj)
carrier
✓ from phonenumbers import carrier
For carrier lookup, import the 'carrier' submodule.
geocoder
✓ from phonenumbers import geocoder
For geographical lookup, import the 'geocoder' submodule.
timezone
✓ from phonenumbers import timezone
For timezone lookup, import the 'timezone' submodule.
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}")
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'phonenumbers'
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.
fixEnsure 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`.
phonenumbers.phonenumberutil.NumberParseException: (0) Missing or invalid default region.
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.
fixWhen 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)`. phonenumbers.phonenumberutil.NumberParseException: (1) The string supplied did not seem to be a phone number.
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.
fixEnsure 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')`. AttributeError: 'str' object has no attribute 'italian_leading_zero'
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.
fixEnsure 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)`. Audit
Dependencies
No dependency data recorded yet.