{"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":"en","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,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}