ipinfo

library5.6.0pypypi✓ verified 84d ago

The official Python client library for the IPinfo API, providing comprehensive IP address details like geolocation, ASN, company, privacy detection, and more. It offers both synchronous and asynchronous interfaces. As of version 5.5.0, it supports new IPinfo Core and Plus API features. The library maintains an active development status with regular, feature-driven releases.

http-networking data

pip install ipinfo

github ↗package ↗homepage ↗docs ↗

INSTALL

IMPORT

SIG · IPINFO

ipinfo

http-networkingpythonv5.6.0

Install

4.5s avg

Import

1063ms

Disk

30MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v5.6.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

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 1.106s · 30.3MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 4.5s · import 1.021s · 32MB

30MB installed

● package 30MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Handler

✓ from ipinfo.handler import Handler

✗ import ipinfo; client = ipinfo.Handler(...)

The Handler class is located in the `ipinfo.handler` submodule, not directly under `ipinfo`.

AsyncHandler

✓ from ipinfo.handler_async import AsyncHandler

✗ from ipinfo.handler import AsyncHandler

The asynchronous client is in a separate submodule, `ipinfo.handler_async`, distinct from the synchronous `ipinfo.handler`.

Details

✓ from ipinfo.details import Details

✗ from ipinfo import Details

The Details object, representing API response data, resides in the `ipinfo.details` submodule.

This quickstart demonstrates how to initialize the synchronous IPinfo client and perform lookups for your own IP address and a specific IP address. Ensure your IPinfo access token is provided either via an environment variable or directly in the code.

import os from ipinfo.handler import Handler # Get your IPinfo access token from environment variable or replace with your token access_token = os.environ.get('IPINFO_TOKEN', 'YOUR_IPINFO_TOKEN') if not access_token or access_token == 'YOUR_IPINFO_TOKEN': print("Warning: Please set the IPINFO_TOKEN environment variable or replace 'YOUR_IPINFO_TOKEN' with your actual token.") else: client = Handler(access_token) # Lookup your own IP address my_ip_details = client.getDetails() print(f"My IP: {my_ip_details.ip}") print(f"My city: {my_ip_details.city}, {my_ip_details.country_name}") # Lookup a specific IP address google_dns_ip = '8.8.8.8' google_details = client.getDetails(google_dns_ip) print(f"\nGoogle DNS IP: {google_details.ip}") print(f"Google DNS ISP: {google_details.org}")

Debug

Known issues

breakingVersion 4.0.0 introduced separate synchronous (`Handler`) and asynchronous (`AsyncHandler`) clients. Code written for older versions using an `async` approach might need to be updated to explicitly use `AsyncHandler` and `await` calls.

fix

For asynchronous operations, ensure you import `AsyncHandler` from `ipinfo.handler_async` and use `await` with its methods. Do not mix sync and async clients/methods.

affects: >=4.0.0

gotchaBatch operation behavior changed significantly in version 4.1.0. `getBatchDetails` now internally chunks large lists of IP addresses and has new options for `batch_size`, `timeout_per_batch`, `timeout_total`, and `raise_on_fail`.

fix

Review the documentation for `getBatchDetails` and adjust existing batch processing logic to leverage the new options for optimal performance and error handling, especially for large lists of IPs.

affects: >=4.1.0

gotchaThe default cache is in-memory and has a finite TTL. For long-running applications or applications requiring persistent caching, implement a custom cache handler using `ipinfo.cache.CacheInterface` or configure the existing cache appropriately to avoid excessive API calls and rate limits.

fix

Consider custom cache implementation (e.g., Redis, disk-based) for production environments or configure the existing cache `ttl` and `maxsize` parameters when initializing the client.

affects: all

gotchaVersion 5.3.0 added support for IPinfo Core and Plus API features. While this is an enhancement, users relying on specific data structures or field availability from previous API versions might encounter new or slightly altered fields in the `Details` object.

fix

Always gracefully handle potentially missing or new fields in the `Details` object, especially when accessing new features or migrating to a higher API tier. Refer to the official IPinfo API documentation for the latest data structures.

affects: >=5.3.0

Errors

Common errors & fixes

AttributeError: 'AsyncHandler' object has no attribute 'getDetails'

Attempting to call a synchronous method (`getDetails`) on an `AsyncHandler` instance, or vice-versa.

fix

Ensure you are using the correct client type for your desired operation. For async operations, use `AsyncHandler` and `await client.getDetails_async()`. For sync, use `Handler` and `client.getDetails()`.

TypeError: __init__() missing 1 required positional argument: 'access_token'

The `Handler` or `AsyncHandler` client was initialized without providing the required `access_token`.

fix

Pass your IPinfo API access token as the first argument when creating a client instance: `client = Handler('YOUR_ACCESS_TOKEN')` or ensure the `IPINFO_TOKEN` environment variable is set.

ipinfo.exceptions.APIError: Bad token

The provided access token is invalid or expired, leading to an API authentication failure.

fix

Verify that your IPinfo access token is correct, has not expired, and has the necessary permissions. Regenerate if necessary from your IPinfo dashboard.

TypeError: object AsyncHandler can't be used in 'await' expression

Trying to `await` the `AsyncHandler` class itself instead of an awaited method call, or calling an async method without `await`.

fix

You `await` the *methods* of the `AsyncHandler` instance, not the instance itself. For example: `details = await client.getDetails()`.

Upgrade

Version history

5.6.0latest on PyPI · released Apr 22, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

13 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/ipinfo/python ↗

packagehttps://pypi.org/project/ipinfo/ ↗

homepagehttps://ipinfo.io ↗

docshttps://ipinfo.io/developers ↗