Install & Compatibility
Where this runs
tested against v3.0.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 17.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.7s · import 0.000s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Client
✓ from geoip2_stubs.webservice import Client
✗ from geoip2-stubs.webservice import Client
This quickstart demonstrates how to use `geoip2.database.Reader` with the `types-geoip2` stub package. When `types-geoip2` is installed alongside `geoip2`, type checkers can infer the types of objects returned by `geoip2` functions and methods, providing benefits like autocompletion and early error detection. You will need to download a GeoLite2-City.mmdb database file from MaxMind for the database lookup functionality.
import geoip2.database
import os
# Ensure you have a GeoLite2-City.mmdb file available for database lookups.
# Download from: https://dev.maxmind.com/geoip/downloads/maxmind-databases/
# For this example, we assume it's in the current directory or specified path.
# Replace with a real path if needed.
DB_PATH = os.environ.get('GEOLITE2_CITY_DB_PATH', 'GeoLite2-City.mmdb')
# If geoip2.database.Reader is initialized without the stub, type checkers might not know its methods.
# With types-geoip2 installed, mypy (or other type checkers) will correctly infer types.
reader: geoip2.database.Reader
try:
reader = geoip2.database.Reader(DB_PATH)
except geoip2.errors.AddressNotFoundError:
print(f"Database file not found at {DB_PATH}. Please provide a valid path or download the database.")
exit(1)
except Exception as e:
print(f"An error occurred initializing the database reader: {e}")
exit(1)
# Example IP address
ip_address = '8.8.8.8' # Google Public DNS
try:
response = reader.city(ip_address)
print(f"IP: {ip_address}")
print(f"Country Name: {response.country.name}")
print(f"City Name: {response.city.name}")
print(f"Latitude: {response.location.latitude}")
print(f"Longitude: {response.location.longitude}")
# Type checker will correctly identify `response` as geoip2.models.City
# and `response.country` as geoip2.records.Country
reveal_type(response) # For mypy to show the inferred type
except geoip2.errors.AddressNotFoundError:
print(f"IP address {ip_address} not found in the database.")
except Exception as e:
print(f"An error occurred during lookup: {e}")
finally:
reader.close()
# To run type checking, save this as `example.py` and run `mypy example.py`
Debug
Known issues
breakingThe `geoip2` package itself started including type annotations from version `4.0.2` onwards. If you are using `geoip2>=4.0.2`, installing `types-geoip2` is unnecessary and may lead to conflicts or outdated type information, as the runtime package's own annotations will often be more accurate.fixUninstall `types-geoip2` if `geoip2` is version 4.0.2 or newer: `pip uninstall types-geoip2`.
affects: geoip2>=4.0.2
gotchaTypeshed stub packages (like `types-geoip2`) are released independently from the runtime library. While their version numbers often align with the runtime package they stub (e.g., `types-foo==1.2.0.YYYYMMDD` for `foo==1.2.*`), internal changes within typeshed's stubs can introduce new type-checking errors even if your runtime `geoip2` package version hasn't changed.fixConsider pinning `types-geoip2` to a specific known-good version (`types-geoip2==X.Y.Z.build_date`) or setting upper bounds that align with your `geoip2` installation (`types-geoip2~=X.Y`). Regularly test type checking when updating dependencies.
affects: All versions
gotchaIn Python's module resolution order for typing, stub files (`.pyi`) from installed stub packages generally take precedence over inline type annotations (`.py`) in the actual library. This means if `types-geoip2` is installed alongside a `geoip2` version that has its own inline types (like `geoip2>=4.0.2`), the `types-geoip2` stubs might be used, potentially overriding newer or more accurate inline types from `geoip2`.fixIf `geoip2` version is `4.0.2` or higher, uninstall `types-geoip2` to rely on the library's built-in type annotations. `pip uninstall types-geoip2`.
affects: All versions (especially when geoip2>=4.0.2 is also installed)
gotchaWhen working with `geoip2` models, MaxMind strongly advises against using values from `names` properties (e.g., `response.city.names['en']`) as keys in databases or dictionaries. These human-readable names are subject to change between releases, potentially leading to broken logic.fixInstead, use stable and unique identifiers such as `geoname_id`, `iso_code`, or `continent.code` for reliable data access.
affects: All versions of `geoip2` (and thus relevant for `types-geoip2` users)
Upgrade
Version history
3.0.0latest on PyPI · released Aug 28, 2021
Audit
Dependencies
geoip2requiredProvides the runtime functionality that types-geoip2 offers type hints for. types-geoip2 is not useful without an installed geoip2 library.