{"id":2662,"library":"phonenumberslite","title":"Phonenumbers Lite","description":"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.","status":"active","version":"9.0.27","language":"python","source_language":"en","source_url":"https://github.com/daviddrysdale/python-phonenumbers","tags":["phone number","validation","formatting","i18n","internationalization","telephony"],"install":[{"cmd":"pip install phonenumberslite","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[{"note":"The primary module for all core functionality.","symbol":"phonenumbers","correct":"import phonenumbers"},{"note":"Used to specify formatting options for phone numbers.","symbol":"PhoneNumberFormat","correct":"from phonenumbers import PhoneNumberFormat"},{"note":"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.","wrong":"from phonenumbers import geocoder","symbol":"geocoder"}],"quickstart":{"code":"import phonenumbers\nfrom phonenumbers import PhoneNumberFormat\nfrom phonenumbers.phonenumberutil import NumberParseException\n\n# Parse a phone number\ntry:\n    # Example with explicit region code for a non-E.164 number\n    number_str_gb = \"020 7946 0958\"\n    parsed_number_gb = phonenumbers.parse(number_str_gb, \"GB\")\n    print(f\"Parsed GB Number: {parsed_number_gb}\")\n\n    # Example with E.164 format (no region needed)\n    number_str_e164 = \"+15555551234\"\n    parsed_number_e164 = phonenumbers.parse(number_str_e164, None)\n    print(f\"Parsed E164 Number: {parsed_number_e164}\")\n\n    # Validate the number\n    is_valid = phonenumbers.is_valid_number(parsed_number_gb)\n    is_possible = phonenumbers.is_possible_number(parsed_number_gb)\n    print(f\"Is GB number valid? {is_valid}\")\n    print(f\"Is GB number possible? {is_possible}\")\n\n    # Format the number\n    formatted_e164 = phonenumbers.format_number(parsed_number_gb, PhoneNumberFormat.E164)\n    formatted_international = phonenumbers.format_number(parsed_number_gb, PhoneNumberFormat.INTERNATIONAL)\n    formatted_national = phonenumbers.format_number(parsed_number_gb, PhoneNumberFormat.NATIONAL)\n    \n    print(f\"Formatted E.164: {formatted_e164}\")\n    print(f\"Formatted International: {formatted_international}\")\n    print(f\"Formatted National: {formatted_national}\")\n\n    # Attempt to parse an invalid number\n    invalid_number_str = \"not a phone number\"\n    phonenumbers.parse(invalid_number_str, \"US\")\n\nexcept NumberParseException as e:\n    print(f\"Error parsing number: {e.args[0]}\")\n\n","lang":"python","description":"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."},"warnings":[{"fix":"If geocoding, carrier, or timezone features are required, `pip uninstall phonenumberslite` and then `pip install phonenumbers`.","message":"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.","severity":"gotcha","affected_versions":"All versions of phonenumberslite"},{"fix":"Always provide a `region_code` (e.g., `phonenumbers.parse('02083661177', 'GB')`) for numbers not in E.164 format, or handle `NumberParseException` appropriately.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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).","message":"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()`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always use `phonenumbers.parse(number_string, region_code)` to obtain a `PhoneNumber` object.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'9.0.27':67 'activ':60 'carrier':38 'current':64 'data':41 'design':13 'environ':51 'footprint':46 'format':16,71 'geocod':37 'googl':9 'i18n':72 'intern':20 'internation':73 'larger':36 'libphonenumb':11 'librari':12,32,58 'limit':56 'lite':2,26 'main':30 'maintain':61 'make':47 'memori':53 'number':22,69 'omit':34 'packag':42 'pars':15 'phone':21,68 'phonenumb':1,31 'phonenumberslit':3 'port':7 'python':6 'reduc':44 'space':55 'specif':33 'store':17 'suitabl':49 'telephoni':74 'timezon':40 'valid':19,70 'version':27,65","created_at":"2026-04-11T01:37:31.893573+00:00","updated_at":"2026-04-16T17:59:57.842998+00:00","problems":[{"fix":"Ensure that either `phonenumbers` or `phonenumberslite` is installed consistently throughout your project's dependencies. If `phonenumberslite` is explicitly desired, verify your import statements are correct (e.g., `import phonenumbers` will work as `phonenumberslite` provides the `phonenumbers` package), and check your Python environment's installed packages. If a dependency truly requires features only in the full `phonenumbers` library, you might need to switch to `pip install phonenumbers` instead of `phonenumberslite`.","cause":"This error often occurs when a project's dependencies expect the full `phonenumbers` library, but `phonenumberslite` is installed, or when `phonenumberslite` is installed but the import statement incorrectly tries to access the top-level `phonenumbers` package directly rather than the specific `phonenumbers` submodule (which exists within the `phonenumberslite` distribution). This can also happen if `phonenumberslite` itself is not correctly installed or recognized by the Python environment.","error":"ModuleNotFoundError: No module named 'phonenumbers'"},{"fix":"When parsing national numbers, always provide a valid two-letter ISO 3166-1 country code as the `region_code` argument, or ensure the number includes the full E.164 international format (e.g., `+CCXXXXXXXXXX`).\n```python\nimport phonenumbers\n\n# Correct: Provide a region code for a national number\nnumber = phonenumbers.parse(\"02081234567\", \"GB\")\nprint(number)\n\n# Correct: Use E.164 format (no region code needed)\nnumber = phonenumbers.parse(\"+442081234567\", None)\nprint(number)\n```","cause":"This exception is raised when the `phonenumbers.parse()` function is called with a national number (without an international dialing code like '+44') and `None` is provided for the `region_code` argument, preventing the library from inferring the correct country context.","error":"phonenumbers.phonenumberutil.NumberParseException: (0) Missing or invalid default region."},{"fix":"If your application requires geocoding, carrier, or timezone functionality, you must install the full `phonenumbers` library instead of `phonenumberslite`.\n```bash\npip uninstall phonenumberslite\npip install phonenumbers\n```\nThen, your imports like `from phonenumbers import geocoder` will work correctly.","cause":"This error occurs when using `phonenumberslite` and attempting to import or access functionality related to geocoding, carrier information, or timezone data (e.g., `phonenumbers.geocoder`, `phonenumbers.carrier`, `phonenumbers.timezone`). `phonenumberslite` is a stripped-down version of the main `phonenumbers` library, specifically designed to omit these larger data packages to reduce its footprint.","error":"AttributeError: module 'phonenumbers' has no attribute 'geocoder'"},{"fix":"Ensure that the input string is a plausible phone number before attempting to parse it. You might want to pre-process the input to remove irrelevant characters or validate its basic structure. Always wrap parsing calls in a `try-except` block to handle invalid inputs gracefully.\n```python\nimport phonenumbers\n\ntry:\n    # Example of an unparseable string\n    number = phonenumbers.parse(\"gibberish\", None)\n    print(number)\nexcept phonenumbers.phonenumberutil.NumberParseException as e:\n    print(f\"Error parsing number: {e}\")\n\n# A valid, parseable number\ntry:\n    number = phonenumbers.parse(\"+15551234567\", None)\n    print(number)\nexcept phonenumbers.phonenumberutil.NumberParseException as e:\n    print(f\"Error parsing number: {e}\")\n```","cause":"This exception indicates that the input string provided to `phonenumbers.parse()` could not be interpreted as a phone number at all, even after attempting to infer a region or with a provided region code. It typically means the input is malformed, contains non-numeric characters in unexpected places, or is simply not a phone number.","error":"phonenumbers.phonenumberutil.NumberParseException: (1) The string supplied did not seem to be a phone number."}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"9.0.38","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/phonenumberslite/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-28","next_check":"2026-07-28","install_tag":null}}