{"id":920,"library":"phonenumbers","title":"Python-phonenumbers","description":"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.","status":"active","version":"9.0.26","language":"python","source_language":"en","source_url":"https://github.com/daviddrysdale/python-phonenumbers","tags":["phone number","validation","formatting","telephony","google","libphonenumber","e.164"],"install":[{"cmd":"pip install phonenumbers","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"phonenumbers","correct":"import phonenumbers"},{"symbol":"parse","correct":"import phonenumbers\nparsed_number = phonenumbers.parse(\"+12133734253\", \"US\")"},{"symbol":"format_number","correct":"from phonenumbers import PhoneNumberFormat\nformatted_number = phonenumbers.format_number(number_obj, PhoneNumberFormat.INTERNATIONAL)"},{"symbol":"is_valid_number","correct":"is_valid = phonenumbers.is_valid_number(number_obj)"},{"note":"For carrier lookup, import the 'carrier' submodule.","symbol":"carrier","correct":"from phonenumbers import carrier"},{"note":"For geographical lookup, import the 'geocoder' submodule.","symbol":"geocoder","correct":"from phonenumbers import geocoder"},{"note":"For timezone lookup, import the 'timezone' submodule.","symbol":"timezone","correct":"from phonenumbers import timezone"}],"quickstart":{"code":"import phonenumbers\nfrom phonenumbers import geocoder, carrier, timezone, PhoneNumberFormat\n\n# 1. Parse a phone number\n#   - The second argument ('GB') provides a default region if the number is not in E.164 format.\n#   - If the number is E.164 (e.g., '+44...'), None can be used as the default region.\nphone_number_str = \"+442083661177\"\ncountry_code = \"GB\" # Default region for parsing, if number is not in international format\n\ntry:\n    parsed_number = phonenumbers.parse(phone_number_str, country_code)\n    print(f\"Parsed Number: {parsed_number}\")\n\n    # 2. Validate the phone number\n    is_valid = phonenumbers.is_valid_number(parsed_number)\n    is_possible = phonenumbers.is_possible_number(parsed_number)\n    print(f\"Is Valid: {is_valid}, Is Possible: {is_possible}\")\n\n    if is_valid:\n        # 3. Format the phone number in various ways\n        national_format = phonenumbers.format_number(parsed_number, PhoneNumberFormat.NATIONAL)\n        international_format = phonenumbers.format_number(parsed_number, PhoneNumberFormat.INTERNATIONAL)\n        e164_format = phonenumbers.format_number(parsed_number, PhoneNumberFormat.E164)\n\n        print(f\"National Format: {national_format}\")\n        print(f\"International Format: {international_format}\")\n        print(f\"E.164 Format: {e164_format}\")\n\n        # 4. Get carrier, region, and timezone information\n        #    Note: These lookups depend on the data included in the phonenumbers library.\n        carrier_name = carrier.name_for_number(parsed_number, \"en\")\n        region_description = geocoder.description_for_number(parsed_number, \"en\")\n        timezones = timezone.time_zones_for_number(parsed_number)\n\n        print(f\"Carrier: {carrier_name}\")\n        print(f\"Region: {region_description}\")\n        print(f\"Timezones: {timezones}\")\n\nexcept phonenumbers.NumberParseException as e:\n    print(f\"Error parsing number: {e}\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"Calling `phonenumbers.parse()` with a non-E.164 number and `None` as the default region will raise a `NumberParseException`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"In version 8.0.0, methods like `_for_region` in `shortnumberinfo.py` no longer accept strings; they now require a `PhoneNumber` object.","severity":"breaking","affected_versions":">=8.0.0"},{"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.","message":"The `PhoneNumberMatcher` class, used for extracting phone numbers from text, is explicitly stated as not being thread-safe.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"The full `phonenumbers` library includes substantial metadata (e.g., geocoder, carrier, timezone data) which can impact memory footprint, especially in resource-constrained environments.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'9.0.26':48 'activ':30 'chang':38 'current':45 'e.164':56 'format':21,52 'function':18 'googl':12,54 'intern':25 'java':42 'libphonenumb':14,55 'librari':15,43 'maintain':31 'number':27,50 'origin':41 'pars':20 'phone':26,49 'phonenumb':3,6 'port':10 'provid':16 'python':2,5,9 'python-phonenumb':1,4 'reflect':36 'regular':33 'robust':17 'store':22 'telephoni':53 'updat':34 'upstream':37 'valid':24,51 'version':46","created_at":"2026-03-29T06:07:44.614796+00:00","updated_at":"2026-04-16T17:59:54.312209+00:00","problems":[{"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`.","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.","error":"ModuleNotFoundError: No module named 'phonenumbers'"},{"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)`.","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.","error":"phonenumbers.phonenumberutil.NumberParseException: (0) Missing or invalid default region."},{"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')`.","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.","error":"phonenumbers.phonenumberutil.NumberParseException: (1) The string supplied did not seem to be a phone number."},{"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)`.","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.","error":"AttributeError: 'str' object has no attribute 'italian_leading_zero'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"9.0.32","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/daviddrysdale/python-phonenumbers","docs":null,"changelog":null,"pypi":"https://pypi.org/project/phonenumbers/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization","communication"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":"verified"}}