Updating GeoIP and GeoLite Databases

There are two methods for automatically updating GeoIP2 and GeoIP Legacy binary databases:

  1. Using MaxMind's GeoIP Update program.
  2. Directly downloading the database.

For clients using our binary database format, we highly recommend using GeoIP Update, but the direct download method is available if necessary. Clients using the CSV-format databases must use the direct download method.

Using GeoIP Update

MaxMind provides the GeoIP Update program, which performs automatic updates for both GeoIP2, GeoIP Legacy, and GeoLite2 binary databases.

1. Install GeoIP Update

Install GeoIP Update. The latest release may be downloaded from GitHub Releases. See the installation instructions for more information. GeoIP Update can also be installed via our Docker image.

If you are using an older version of GeoIP Update, you may need to upgrade to GeoIP Update 4.x or later version. The 4.x and later versions meet our requirement for using TLS 1.2 or greater for all requests to our servers to keep your data secure.

Please see our upgrade guide for more information on upgrading from an older version of GeoIP Update.

2. Obtain GeoIP.conf with Account Information

Log in to your account portal to download a partially pre-filled configuration file and save it in your configuration directory (e.g., /usr/local/etc/) as GeoIP.conf. You will need to replace the YOUR_LICENSE_KEY_HERE placeholder with an active license key associated with your MaxMind account. You can see your license key information on your account License Keys page.

You may also write this file by hand using the template below (not recommended).

Note that for geoipupdate versions less than 2.5.0, use UserId instead of AccountID and ProductIds instead of EditionIDs.

3. Run GeoIP Update

Run geoipupdate. To fully automate this process on Linux or Unix, use a crontab file like:

This crontab file would run twice a week, and it would email you the results.

If you are running a firewall, geoipupdate requires that the DNS and HTTPS (443) ports be open.

Troubleshooting

If you receive an error when running GeoIP Update, you can use the verbose option by adding the -v flag. This will print out each step taken as it runs. The information provided can often help to clarify issues. Additional instructions for GeoIP Update can be viewed when running man geoipupdate on the command line.

Please note that GeoIP Update requires current access to database updates to run properly. If your subscription needs to be renewed, updates can be purchased while logged into your Account Summary page.

Updating to the latest release of GeoIP Update may be required to resolve some errors.

Directly downloading databases

This is only recommended for systems unable to use GeoIP Update or for clients using the CSV-format databases.

In order to download the databases from a script or program, please use the permalinks found on the GeoIP download page.

  1. In the “Download Links” column, click “Get Permalink(s)” for the desired database.
  2. Copy the permalink(s) provided in the modal window.
  3. Replace YOUR_LICENSE_KEY with your license key.
  4. If you are using wget or curl from a shell script, please be sure to quote the URL.

This download will return a compressed file in gzip (for binary) or zip (for CSV) format, which can be uncompressed using a program like 7-Zip or gzip.

Checking for the Latest Release Date

You can check the date of a given database’s latest release by issuing a HEAD request for that database’s download permalink URL. The download permalink can be found in the Download Databases section of your account portal.

For example, using the permalink for the GeoIP2 City CSV database, you can issue a command like the following:

Where YOUR_LICENSE_KEY is a placeholder for your account’s actual license key.

In the response, you can check the last-modified header for the file’s build date, or you can check the content-disposition header for the date that would appear in the file name. These checks can be incorporated into your own script or program, according to your needs.

This method only issues a HEAD request, rather than a download request, so running this check won’t count against your daily database download limit.

Third-Party Tools

Use at your own risk. MaxMind does not offer support for these tools and has not reviewed the code.

  • Geoip2 Update - A PHP tool for updating MaxMind GeoLite2 and GeoIP2 databases from your script or via Composer.

Download limits

MaxMind reserves the right to limit the number of downloads made within a limited period of time.

This page was last updated on June 17, 2021.