closeio-phonenumbers
Low-memory CPython bindings for Google's C++
libphonenumber implementation.
It provides a compatibility-focused subset of the widely used phonenumbers
Python API, backed by libphonenumber's native parser, formatter, matcher, and
geocoder.
The distribution is named closeio-phonenumbers, while the installed import
package is named phonenumbers:
import phonenumbers
Do not install closeio-phonenumbers and the pure-Python phonenumbers
distribution in the same environment. Both provide the same import package.
This is not yet a drop-in replacement for every phonenumbers API. See
COMPATIBILITY.md for the supported surface.
Features
- International phone-number parsing, formatting, and validation
- Region and number-type lookup
- Phone-number extraction from Unicode text
- Offline geographic descriptions
- Lazy phone-prefix timezone lookup
- Typed Python interfaces
- Repaired wheels with non-system native dependencies bundled
Installation
python -m pip install closeio-phonenumbers
Prebuilt wheels are available for the following targets:
| Python | Platform | Architectures |
|---|---|---|
| CPython 3.12–3.14 | Linux (manylinux 2.28+) | x86-64, ARM64 |
| CPython 3.12–3.14 | macOS 15+ | x86-64, Apple Silicon |
Installing a wheel does not require a compiler or ICU, Protobuf, or libphonenumber development packages.
Usage
import phonenumbers
from phonenumbers import geocoder, timezone
number = phonenumbers.parse("+1 415-333-4444")
phonenumbers.is_valid_number(number)
# True
phonenumbers.format_number(number, phonenumbers.PhoneNumberFormat.E164)
# "+14153334444"
phonenumbers.region_code_for_number(number)
# "US"
geocoder.description_for_number(number, "en")
# "San Francisco, CA"
timezone.time_zones_for_number(number)
# ("America/Los_Angeles",)
Find numbers in text with PhoneNumberMatcher:
text = "Call +1 415-333-4444 or +44 20 7219 4272."
for match in phonenumbers.PhoneNumberMatcher(text, region=None):
print(match.start, match.end, match.raw_string)
Versioning and source inputs
Versions have the form <libphonenumber version>.<binding revision>. For
example, 9.0.34.1 is binding revision 1 over libphonenumber 9.0.34.
The libphonenumber and fallback Abseil source archives are pinned by SHA-256. Both archives are included in the source distribution, allowing it to build without network access once the declared Python and system build dependencies are installed. Geographic and timezone metadata come from the same pinned libphonenumber release.
Building from source
A source build requires Python 3.12–3.14, a C++17 compiler, CMake, Ninja, ICU
development headers, Protocol Buffers headers, and protoc. A Git checkout
also needs the pinned source archives; a source distribution already includes
them.
On Ubuntu:
sudo apt-get install \
build-essential cmake ninja-build pkg-config python3-dev \
libicu-dev libprotobuf-dev protobuf-compiler
python tools/fetch_libphonenumber.py
python -m pip install build pytest
python -m build --wheel
python -m pip install dist/*.whl
python -m pytest
On macOS:
brew install cmake icu4c ninja pkg-config protobuf
export CMAKE_PREFIX_PATH="$(brew --prefix icu4c):$(brew --prefix protobuf)"
export PKG_CONFIG_PATH="$(brew --prefix icu4c)/lib/pkgconfig:\
$(brew --prefix protobuf)/lib/pkgconfig"
python tools/fetch_libphonenumber.py
python -m pip install build pytest
python -m build --wheel
python -m pip install dist/*.whl
python -m pytest
Use python -m cibuildwheel --platform linux or --platform macos to
produce repaired wheels using the configuration in pyproject.toml.
Contributing
See CONTRIBUTING.md for development checks and instructions for updating the pinned libphonenumber metadata.
License
Licensed under the Apache License 2.0. See LICENSE and NOTICE for attribution. This project is not affiliated with or endorsed by Google.
1 maintainer
Release files for closeio-phonenumbers 9.0.34.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| closeio_phonenumbers-9.0.34.2.tar.gz | 14.8 MB | Details |
Built distributions (wheels)
Total release size: 224.5 MB
Release files / closeio_phonenumbers-9.0.34.2.tar.gz
| Download URL | closeio_phonenumbers-9.0.34.2.tar.gz |
|---|---|
| Size | 14.8 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
bf5c29fd674945ff81dc71a0d303ba5a9fd066493bdb4928a8018720ac5e4986
|
|
BLAKE2b-256 checksum How to use checksums |
52d71c492e1c152ef417a0ba8a2befc5465f3f6b92b0539cb22193d8e5ea9624
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 23, 2026.
Transparency logRelease files / closeio_phonenumbers-9.0.34.2-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | closeio_phonenumbers-9.0.34.2-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 17.0 MB |
| Tags | CPython 3.14 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
a204cae2f272ebd27384709f0c0c0ede9a43f5dc35559edf3eb98f99db529fe6
|
|
BLAKE2b-256 checksum How to use checksums |
a1d9d5881d9d85cf32a756d242bb827021c44bb304afe12afa3900087ec40d26
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 23, 2026.
Transparency logRelease files / closeio_phonenumbers-9.0.34.2-cp314-cp314-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl
| Download URL | closeio_phonenumbers-9.0.34.2-cp314-cp314-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl |
|---|---|
| Size | 16.7 MB |
| Tags | CPython 3.14 Linux glibc 2.26+ ARM64 Linux glibc 2.28+ ARM64 |
|
SHA-256 checksum How to use checksums |
fef52880721a41371a2fed4a1ede98fddb327a848109e08fb42bfd0a7810d610
|
|
BLAKE2b-256 checksum How to use checksums |
90671632361bfafd83606387cefa6de827e568a6180380ecd71cdad783bb6146
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 23, 2026.
Transparency logRelease files / closeio_phonenumbers-9.0.34.2-cp314-cp314-macosx_15_0_x86_64.whl
| Download URL | closeio_phonenumbers-9.0.34.2-cp314-cp314-macosx_15_0_x86_64.whl |
|---|---|
| Size | 18.2 MB |
| Tags | CPython 3.14 macOS 15.0+ x86-64 |
|
SHA-256 checksum How to use checksums |
5b507b7ae8d46b9a7cb0e6fb1f4dfd43f3b1476d081aa14995f33408b5cdf30b
|
|
BLAKE2b-256 checksum How to use checksums |
8984754ab4762006350ae43fe964c303e813e26e30ff36aa35fbe176f0cbdda4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 23, 2026.
Transparency logRelease files / closeio_phonenumbers-9.0.34.2-cp314-cp314-macosx_15_0_arm64.whl
| Download URL | closeio_phonenumbers-9.0.34.2-cp314-cp314-macosx_15_0_arm64.whl |
|---|---|
| Size | 18.0 MB |
| Tags | CPython 3.14 macOS 15.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
a62d73301f1350300c2806d5dc0d680d4fc569e912d35dc798873d200be390c2
|
|
BLAKE2b-256 checksum How to use checksums |
26e29b19054e9d3eb266e0064df0689e7343fa50a423914edf8edf5f609e948d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 23, 2026.
Transparency logRelease files / closeio_phonenumbers-9.0.34.2-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | closeio_phonenumbers-9.0.34.2-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 17.0 MB |
| Tags | CPython 3.13 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
2b57cd5dc30f7c22121a10a59fba38764bfc4c1c975aef1697d149f761933d7c
|
|
BLAKE2b-256 checksum How to use checksums |
70de04805c269206f558f7dd2f1a3f70144f5ac3faea97e55da36a4acc82ff30
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 23, 2026.
Transparency logRelease files / closeio_phonenumbers-9.0.34.2-cp313-cp313-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl
| Download URL | closeio_phonenumbers-9.0.34.2-cp313-cp313-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl |
|---|---|
| Size | 16.7 MB |
| Tags | CPython 3.13 Linux glibc 2.26+ ARM64 Linux glibc 2.28+ ARM64 |
|
SHA-256 checksum How to use checksums |
29ece5632eef2a944af314258ec95c6398c4a9def175b9764584b288f9ff13e2
|
|
BLAKE2b-256 checksum How to use checksums |
88a3aa5db545aeda864bef943afcc23c7a1b40ed315b3592ece5f85213975bb0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 23, 2026.
Transparency logRelease files / closeio_phonenumbers-9.0.34.2-cp313-cp313-macosx_15_0_x86_64.whl
| Download URL | closeio_phonenumbers-9.0.34.2-cp313-cp313-macosx_15_0_x86_64.whl |
|---|---|
| Size | 18.2 MB |
| Tags | CPython 3.13 macOS 15.0+ x86-64 |
|
SHA-256 checksum How to use checksums |
04d33297efd0a55fbe54f9c53944855db45bfb87fcbe869af2f766a28dec9010
|
|
BLAKE2b-256 checksum How to use checksums |
869083032a19a19a2de909a10ffa65914275d0fc6ef32290d90444ef381ec67a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 23, 2026.
Transparency logRelease files / closeio_phonenumbers-9.0.34.2-cp313-cp313-macosx_15_0_arm64.whl
| Download URL | closeio_phonenumbers-9.0.34.2-cp313-cp313-macosx_15_0_arm64.whl |
|---|---|
| Size | 18.0 MB |
| Tags | CPython 3.13 macOS 15.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
70634ddf5243092a29c5d6d82321168d6ba087a0b4c242bc1bc3f2cdbe8ea89f
|
|
BLAKE2b-256 checksum How to use checksums |
6a1febd7cc66b421503d112f7d950ca0852f2f1958d738b81fba4f25e2c7dafe
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 23, 2026.
Transparency logRelease files / closeio_phonenumbers-9.0.34.2-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | closeio_phonenumbers-9.0.34.2-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 17.0 MB |
| Tags | CPython 3.12 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
68e25faec360f32bc8fc9663deb18d0928c59652fc49fe25736adb9d6d949db8
|
|
BLAKE2b-256 checksum How to use checksums |
4116aa44018ac395b35d3ed002bda4ab8570d9ee86b71d0d9440cd296f56b097
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 23, 2026.
Transparency logRelease files / closeio_phonenumbers-9.0.34.2-cp312-cp312-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl
| Download URL | closeio_phonenumbers-9.0.34.2-cp312-cp312-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl |
|---|---|
| Size | 16.7 MB |
| Tags | CPython 3.12 Linux glibc 2.26+ ARM64 Linux glibc 2.28+ ARM64 |
|
SHA-256 checksum How to use checksums |
8fffc900265edc1e9b602d537c30773a0bbed328a2144bb1c694a4fe2cff4172
|
|
BLAKE2b-256 checksum How to use checksums |
1d2ef9f3780c009cb395eb812aeb187270f68472b4af7adf43fc9f8451137ded
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 23, 2026.
Transparency logRelease files / closeio_phonenumbers-9.0.34.2-cp312-cp312-macosx_15_0_x86_64.whl
| Download URL | closeio_phonenumbers-9.0.34.2-cp312-cp312-macosx_15_0_x86_64.whl |
|---|---|
| Size | 18.2 MB |
| Tags | CPython 3.12 macOS 15.0+ x86-64 |
|
SHA-256 checksum How to use checksums |
e49e466915dfea2cb0f00da7d50dccb4951d14f4cbd11180a55ca056490866d7
|
|
BLAKE2b-256 checksum How to use checksums |
6e19fcc7c91bb7ac3d5ef76e3794f3f5826df5df8dd5be071a8f52558a679d28
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 23, 2026.
Transparency logRelease files / closeio_phonenumbers-9.0.34.2-cp312-cp312-macosx_15_0_arm64.whl
| Download URL | closeio_phonenumbers-9.0.34.2-cp312-cp312-macosx_15_0_arm64.whl |
|---|---|
| Size | 18.0 MB |
| Tags | CPython 3.12 macOS 15.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
d1860cfe277d746900aed29b01f9e5ca7d906b3ac54c97757232f5137ee03970
|
|
BLAKE2b-256 checksum How to use checksums |
6321fc36fe785dfe6d557d078359e3c37427a83fb30027542fbff150ed607d91
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 23, 2026.
Transparency log
