How to install PHP GeoIP extension & GeoLite2 library (databases included)

This in-depth article will guide you on how to install PHP GeoIP, which can be necessary for handling visitors with country-based tasks using PHP.

GeoIP is a PHP extension to get location from an IP address. The primary location information including City, Sate, Country, Longitude, Latitude, ISP and other various information.

The PHP GeoIP extension works by using the geolocation data created by MaxMind Inc., a US-based leading company in providing IP intelligence and online fraud detection tools.

The extension reads the IP address, then checks with the geolocation data inside the bundled database file (provided by MaxMind), and returns the geolocation information.

Currently, there are two main methods for using GeoIP in PHP:

• PHP GeoIP PECL extension (Deprecated): The original PHP GeoIP extension works as a PHP PECL extension (geoip.so in Linux, php_geoip.dll in Windows), using GeoIP Legacy databases. MaxMind has planned to retire the GeoIP Legacy databases at the end of May 2022. While the legacy databases are still usable, they won’t be updated or supported after that date.
  *There is also a client API for GeoIP Legacy Database, but it is not widely used as PECL extension.
• PHP GeoIP2 client library (recommended): Using the newer GeoIP2 databases, doesn’t require installing PHP extensions and only needs the GeoIP2 database + GeoIP2 PHP API to work. This is the recommended method.

*The deprecated PHP PECL GeoIP extension will not work with GeoIP2 databases.

For GeoIP2 method in this tutorial, we will use the free database from MaxMind, which is called GeoLite2.

As the above recommended option, using GeoIP2 is preferred, as it includes future updates, that means more data accuracy compared to the legacy PECL extension method.

However, in this in-depth tutorial, we will introduce both legacy GeoIP and newer GeoIP2 installation methods for you to pick, since there are still servers using old PHP versions, and in general, unless you want absolute precise location, the Legacy database, or the newer GeoIP2 free version – GeoLite2, are more than enough to provide fairly accurate geolocation information of the IP addresses.

We will also provide downloadable database files/URLs, saving your time looking for them.

You need the GeoIP (legacy) / GeoIP2 databases downloaded and stored to a accessible location first for PHP to read and make use of the database. It could be either at the same project’s root directory, or in system public access directories, such as /usr/local/share/ directory in Linux.

For GeoIP legacy databases, navigate to this URL and scroll to the Download section:

https://mailfud.org/geoip-legacy/

For GeoIP2 free version – GeoLite2 databases, you can register for a MaxMind account to download the free databases.

Fortunately, we’re going to save you some time. Just navigate to this URL and scroll to the Download section:

https://github.com/P3TERX/GeoLite.mmdb

You can pick the type of database you want there to download.

After downloaded, extract the package and copy the file to the above mentioned, recommended location. For example:

Afteer copying the database file to the preferred location, we can start the extension installation.

To install PHP GeoIP extension, depends on the operation system, the method will be different.

Getting PHP GeoIP extension installed on Windows is pretty easy, you just have to download it, and copy the DLL extension file to the ext folder inside PHP directory, and configure php.ini to load that extension.

To download latest GeoIP version for Windows, navigate to this URL and scroll down to the DLL List table to pick the correct version to download:

https://pecl.php.net/package/geoip/1.1.1/windows

To pick the right version to download, here are our quick tips:

• PHP version: Unfortunately, the GeoIP PECL extension only support maximum of PHP version 7.4 on Windows.
• Thread safety: If you’re using native Apache Handler (LoadModule or default XAMPP Apache configuration) or native IIS, pick Thread Safe version. If you use FastCGI for Apache, use the Non Thread Safe version.
• x86 and x64: If your Windows version is 32-bit, use x86 version. Else, x64 is for 64-bit.

*For example, with PHP 7.3, default Apache Handler, Windows 64-bit, the right version to pick is 7.3 Thread Safe (TS) x64 file.

After downloaded the file, extract it, we will have a number of files but the only one we need is the <strong>php_geoip.dll</strong> file:

Copy the file to the ext directory of your PHP installation. For example, with XAMPP, the path will be [XAMPP Directory\php\ext\:

Finally, enable the extension by modifying php.ini, the file is usually inside PHP installation directory.

Insert this line into the end of php.ini file if it doesn’t exist:

If the line existed for some reason, it would have the semicolon comment at the start:

Then, just remove the ; sign.

Save the file. Skip to the 2.3. Verify that installation works below.

For CentOS or RedHat-based OS, install PHP GeoIP PECL extension by this command:

For Ubuntu or Debian-based OS, install the extension by this command:

After successful installation, move on the to next section for verifying that installation works.

*We will constantly update this article with more operating systems, along with troubleshooting installation issues.

On either operating system, create a new PHP file, insert these lines:

Save the file and open it on your browser. Look for the geoip text, if you see this section, the installation is successfully done and GeoIP should work:

Below is an example on how to use PHP GeoIP PECL extension for general geolocation information. The database path for the GeoIP.dat is where we saved as mentioned above.

To see the full list of GeoIP functions, check the official PHP.net GeoIP extension page.

This is the recommended method, making GeoIP up to date, easier to use, and less chance of having incompatibility issues on different operating system.

To install PHP GeoIP2 using GeoIP2 PHP API, it is recommended to have Composer installed first.

We assumes that you already have Composer installed, if not, here is the quick way to get it installed.
On your project’s root directory:

To quickly install Composer, run this command:

This will download the composer.phar file and save it to the current directory.
Then, run this command to install the latest GeoIP2 PHP API version:

This will add a vendor directory to your current one if it doesn’t exist, along with the composer.json and composer.lock file.

Navigate to Composer download page:

https://getcomposer.org/download/

Download and run the Composer-Setup.exe file to install the latest composer version.

Then, use this command at your project root directory:

Similar with Linux, this will have composer.json, composer.lock file and vendor directory created.

This is a quick example on how to get basic Country geolocation information based on an IP address by using GeoIP2 PHP API. The GeoLite2 database path is where the downloaded database file in the previous section get saved as recommended.

GeoIP has many usages in PHP, mainly for handling visitors based on the country, or more detailed, city, ISP, etc. By default, the free database can already provide pretty accurate information, but you can always subscribe for the paid GeoIP2 database which will be more accurate (check the pricing here), which could be utilized for fraud prevention in ecommerce websites.

We hope that the tutorial is helpful for you, as we will constantly update and add more useful PHP guides.