geoip2-tools

0.1.1 · active · verified Thu Apr 16

geoip2-tools provides command-line utilities for the automatic update and administration of MaxMind GeoIP2 databases. It simplifies the process of downloading and managing the GeoLite2 or GeoIP2 databases. The current version is 0.1.1, and the project appears to be in a stable state with a slow release cadence, primarily focusing on bug fixes.

Common errors

```
Command 'geoip2-tools' not found
```
cause The `geoip2-tools` package is not installed or the executable is not in your system's PATH.

fix Ensure the package is installed: `pip install geoip2-tools`. If installed in a virtual environment, ensure the environment is activated. If installed globally, verify your PATH.
```
Neither GEOIP2_ACCOUNT_ID nor GEOIP2_LICENSE_KEY were provided.
```
cause The MaxMind credentials required for downloading database updates are missing.

fix Set your MaxMind Account ID and License Key as environment variables: `export GEOIP2_ACCOUNT_ID="YOUR_ACCOUNT_ID"` and `export GEOIP2_LICENSE_KEY="YOUR_LICENSE_KEY"`. Replace placeholders with your actual credentials. Alternatively, configure them in a `geoip2-tools.yaml` file.
```
requests.exceptions.HTTPError: 401 Client Error: Unauthorized for url: ...
```
cause Your MaxMind Account ID or License Key are incorrect or have expired, leading to an authentication failure when trying to download databases.

fix Double-check your `GEOIP2_ACCOUNT_ID` and `GEOIP2_LICENSE_KEY` values for correctness. Verify them on your MaxMind account page. Ensure your license key is still active.

Warnings

gotcha This library is designed for *managing* GeoIP2 databases (downloading, updating). It is not for performing GeoIP lookups within Python code. For that, you should use the `geoip2` library directly (e.g., `from geoip2.database import Reader`).
Fix: Use `pip install geoip2` and `from geoip2.database import Reader` for in-application lookups.
gotcha To download or update GeoIP2 databases, you *must* provide your MaxMind Account ID and License Key. These can be set via `GEOIP2_ACCOUNT_ID` and `GEOIP2_LICENSE_KEY` environment variables, or through a configuration file.
Fix: Before running `geoip2-tools update`, set environment variables: `export GEOIP2_ACCOUNT_ID='...'` and `export GEOIP2_LICENSE_KEY='...'`. Alternatively, configure them in a `geoip2-tools.yaml` file.
gotcha The default database download location might not be suitable for your production environment. Databases are typically stored in `/usr/local/share/GeoIP` (Linux) or a user's data directory. Consider configuring a custom path if needed.
Fix: Use the `--database-path` option with CLI commands or configure the `database_path` in `geoip2-tools.yaml` to specify a desired storage location.

Install

pip install geoip2-tools Install geoip2-tools

Imports

Manager
```
from geoip2_tools.manager import Manager
```
While `geoip2-tools` is primarily a CLI tool, the `Manager` class can be imported for programmatic control over database updates and administration tasks within custom Python scripts.

Quickstart

This quickstart demonstrates how to configure your MaxMind credentials via environment variables and then use the `geoip2-tools` CLI to update and check the status of your GeoIP2 databases. Ensure you replace the placeholder credentials with your own.

# 1. Set your MaxMind account ID and license key as environment variables
#    (Replace 'YOUR_ACCOUNT_ID' and 'YOUR_LICENSE_KEY' with your actual credentials)
export GEOIP2_ACCOUNT_ID="YOUR_ACCOUNT_ID"
export GEOIP2_LICENSE_KEY="YOUR_LICENSE_KEY"

# 2. Run the update command to download/update databases
geoip2-tools update

# 3. Check the status of your databases
geoip2-tools status

view raw JSON →