Google's libphonenumber is the reference library for phone numbers, written in Java. Many other libraries port it or reuse its data. This page explains how libphonenumber-js relates to it and what to use in each language.
What they have in common
All of them use the same numbering plan data, which Google maintains and updates as countries change their rules. That is why a number that is valid in one is almost always valid in the others.
How libphonenumber-js differs
libphonenumber-js is an independent rewrite for JavaScript. It is not an official Google project. Its documentation explains why it exists: Google's official JavaScript port is tightly coupled to the Closure framework and, once bundled, is about 550 kB, while libphonenumber-js is much smaller and lets you choose a smaller data set.
- It can find phone numbers inside a block of text with findPhoneNumbersInText(). Google's JavaScript port cannot.
- It does not provide geolocation by phone number, and it has no carrier data.
- It skips special cases that people do not type into a form: emergency numbers like 911, SMS short codes, numbers starting with *, alphabetic numbers like 1-800-GOT-MILK, and combined extensions.
- International numbers are formatted with spaces only, with no hyphens or brackets: +44 20 7946 0958.
- For non-geographic numbers, country is undefined instead of 001.
- It has no formatNumberForMobileDialing(), so it never adds the carrier codes some countries, such as Brazil and Colombia, need when dialing from a mobile.
- It has several metadata builds (min, max, mobile) so you can trade size for strictness.
Libraries by language
If you are not writing JavaScript, these are the common choices. All are based on Google's data.
| Language | Library | Notes |
|---|---|---|
| Java and Android | google/libphonenumber | The reference implementation, with geocoder and carrier data. |
| JavaScript | libphonenumber-js | Smaller rewrite, runs in browsers and Node.js. |
| JavaScript | google-libphonenumber | Port of the Google Closure version, larger bundle. |
| Python | phonenumbers | Python port with geocoder and carrier data. |
| PHP | giggsey/libphonenumber-for-php | Port used by many PHP frameworks. |
| C# | libphonenumber-csharp | Port for .NET. |
| Go | nyaruka/phonenumbers | Port for Go. |
Which should you use?
For a web app, libphonenumber-js is the usual choice because of its size. For a Java or Python backend that needs the city or the carrier, use the matching port of the full library. For validation only, any of them is fine, and you can use different ones in the browser and on the server because they share data.