{"library":"geoip2","title":"MaxMind GeoIP2 Python API","description":"The geoip2 Python package provides an API for both MaxMind's GeoIP2 and GeoLite2 web services and local databases. It allows developers to perform IP geolocation lookups, retrieving information such as country, city, and ASN details. The library is actively maintained, with version 5.2.0 being the latest stable release, and follows semantic versioning with a regular release cadence.","language":"python","status":"active","last_verified":"Wed May 20","install":{"commands":["pip install geoip2"],"cli":null},"imports":["from geoip2.database import Reader","from geoip2.webservice import Client","from geoip2.webservice import AsyncClient","from geoip2.errors import AddressNotFoundError"],"auth":{"required":false,"env_vars":[]},"quickstart":{"code":"import os\nimport geoip2.database\nfrom geoip2.errors import AddressNotFoundError\n\n# --- Using a local GeoLite2 City database ---\n# 1. Download GeoLite2 City database from MaxMind (requires account):\n#    https://dev.maxmind.com/geoip/geolite2-free-geolocation-data\n# 2. Extract the .mmdb file (e.g., GeoLite2-City.mmdb) and place it in a known directory.\n\ndatabase_path = os.environ.get('GEOLITE2_CITY_DB_PATH', './GeoLite2-City.mmdb')\n\nif not os.path.exists(database_path):\n    print(f\"Error: GeoLite2 City database not found at {database_path}.\")\n    print(\"Please download it from MaxMind and update GEOLITE2_CITY_DB_PATH environment variable or file path.\")\nelse:\n    try:\n        # Reader objects are expensive to create and should be reused across lookups.\n        with geoip2.database.Reader(database_path) as reader:\n            ip_address = '8.8.8.8'\n            try:\n                response = reader.city(ip_address)\n                print(f\"IP: {ip_address}\")\n                print(f\"  Country: {response.country.name} ({response.country.iso_code})\")\n                print(f\"  City: {response.city.name}\")\n                print(f\"  Location: Latitude {response.location.latitude}, Longitude {response.location.longitude}\")\n            except AddressNotFoundError:\n                print(f\"IP address {ip_address} not found in the database.\")\n            except Exception as e:\n                print(f\"An error occurred during lookup for {ip_address}: {e}\")\n\n\n# --- Using the GeoIP2 Web Service (requires MaxMind Account ID and License Key) ---\n# MAXMIND_ACCOUNT_ID and MAXMIND_LICENSE_KEY should be set as environment variables\naccount_id = os.environ.get('MAXMIND_ACCOUNT_ID')\nlicense_key = os.environ.get('MAXMIND_LICENSE_KEY')\n\nif account_id and license_key:\n    print(\"\\n--- Web Service Lookup ---\")\n    try:\n        # Client objects are also expensive and should be reused.\n        with geoip2.webservice.Client(account_id, license_key) as client:\n            ip_address_ws = '1.1.1.1'\n            try:\n                response_ws = client.city(ip_address_ws)\n                print(f\"IP: {ip_address_ws}\")\n                print(f\"  Country: {response_ws.country.name} ({response_ws.country.iso_code})\")\n                print(f\"  City: {response_ws.city.name}\")\n                print(f\"  Location: Latitude {response_ws.location.latitude}, Longitude {response_ws.location.longitude}\")\n            except AddressNotFoundError:\n                print(f\"IP address {ip_address_ws} not found via web service.\")\n            except Exception as e:\n                print(f\"An error occurred during web service lookup for {ip_address_ws}: {e}\")\n    except Exception as e:\n        print(f\"Error initializing web service client: {e}\")\nelse:\n    print(\"\\nSkipping web service example: MAXMIND_ACCOUNT_ID and MAXMIND_LICENSE_KEY environment variables not set.\")","lang":"python","description":"This example demonstrates how to perform a geolocation lookup using a local GeoLite2 City database. It also includes an optional section for using the GeoIP2 Web Service, which requires a MaxMind account ID and license key. Remember to download a MaxMind database (e.g., GeoLite2-City.mmdb) and specify its path for the local database example. Reader and Client objects should be initialized once and reused for performance.","tag":null,"tag_description":null,"last_tested":"2026-04-24","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]},"compatibility":{"tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","last_tested":"2026-05-20","installed_version":"5.1.0","pypi_latest":"5.2.0","is_stale":true,"summary":{"python_range":"3.10–3.9","success_rate":100,"avg_install_s":4.5,"avg_import_s":0.15,"wheel_type":"wheel"},"results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"geoip2","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.17,"mem_mb":5,"disk_size":"30.2M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"geoip2","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.17,"mem_mb":5,"disk_size":"30.4M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"geoip2","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":5.4,"import_time_s":0.11,"mem_mb":5,"disk_size":"32M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"geoip2","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.12,"mem_mb":5,"disk_size":"33M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"geoip2","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.21,"mem_mb":6,"disk_size":"33.1M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"geoip2","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.23,"mem_mb":6,"disk_size":"33.4M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"geoip2","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":4.3,"import_time_s":0.18,"mem_mb":6,"disk_size":"35M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"geoip2","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.17,"mem_mb":6,"disk_size":"36M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"geoip2","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.18,"mem_mb":5.7,"disk_size":"24.9M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"geoip2","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.2,"mem_mb":5.7,"disk_size":"25.2M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"geoip2","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":3.3,"import_time_s":0.18,"mem_mb":5.7,"disk_size":"27M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"geoip2","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.19,"mem_mb":5.7,"disk_size":"28M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"geoip2","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.17,"mem_mb":5.7,"disk_size":"24.3M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"geoip2","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.17,"mem_mb":5.7,"disk_size":"24.4M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"geoip2","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":3.5,"import_time_s":0.16,"mem_mb":5.7,"disk_size":"27M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"geoip2","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.17,"mem_mb":5.7,"disk_size":"27M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"geoip2","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.07,"mem_mb":2.5,"disk_size":"30.3M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"geoip2","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":2.5,"disk_size":"30.3M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"geoip2","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":6.1,"import_time_s":0.07,"mem_mb":2.5,"disk_size":"33M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"geoip2","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":2.5,"disk_size":"33M"}]}}