Registry / http-networking / ip2location

ip2location

JSON →
library8.11.0pypypi✓ verified 85d ago

This is an IP geolocation library that enables the user to find the country, region, city, latitude and longitude, ZIP code, time zone, ISP, domain name, area code, weather info, mobile info, elevation, usage type, address type and IAB category from an IP address. It supports both IPv4 and IPv6 lookup.

pip install IP2Location
INSTALL
IMPORT
SIG · IP2LOCATION
I
ip2location
http-networkingpythonv8.11.0
Install
1.5s avg
Import
71ms
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v8.11.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.103.920 runs
installs and imports cleanly · install 0.0s · import 0.074s · 17.9MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 1.5s · import 0.068s · 18MB
16MB installed
● package 16MB
Code
Verified usage

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

IP2Location
import IP2Location
from ip2locationio import IPGeolocation
The `ip2locationio` package is for the IP2Location.io web API, not the local BIN database library.

This quickstart demonstrates how to load an IP2Location BIN database file and query geolocation information for an IP address. You must download a database file separately and provide its path.

import IP2Location import os # NOTE: You must download an IP2Location BIN database file separately. # For a free LITE database: https://lite.ip2location.com/ip2location-lite # Place the .BIN file in a 'data' directory or specify its full path. DB_PATH = os.path.join("data", "IP2LOCATION-LITE-DB1.BIN") # Replace with your actual database file # Ensure the database file exists if not os.path.exists(DB_PATH): print(f"Error: IP2Location BIN database not found at {DB_PATH}") print("Please download a database from https://lite.ip2location.com/ip2location-lite") else: try: # Initialize the IP2Location object with the database file # Use 'FILE_IO' (default) or 'SHARED_MEMORY' if your system has enough RAM (IP2Location.IP2LOCATION_SHARED_MEMORY) database = IP2Location.IP2Location(DB_PATH) # Lookup an IP address ip_address = "8.8.8.8" # Google Public DNS rec = database.get_all(ip_address) if rec: print(f"IP Address: {ip_address}") print(f"Country Code: {rec.country_short}") print(f"Country Name: {rec.country_long}") print(f"Region Name: {rec.region}") print(f"City Name: {rec.city}") print(f"Latitude: {rec.latitude}") print(f"Longitude: {rec.longitude}") print(f"ISP: {rec.isp}") # Access other fields like rec.zipcode, rec.timezone, etc. else: print(f"No data found for IP: {ip_address}") print("This might mean your database does not contain this IP range or is outdated.") except Exception as e: print(f"An error occurred: {e}") print("Ensure your BIN database is compatible with the library version and not corrupted.")
Debug
Known issues
breakingThe library relies on a separate IP2Location BIN database file, which must be downloaded and kept updated by the user. It does not work out-of-the-box without this file.
fix
Download the appropriate BIN database from IP2Location (e.g., https://lite.ip2location.com/ip2location-lite for free LITE data) and provide its path during `IP2Location.IP2Location()` initialization.
affects: All versions
gotchaThere are two distinct Python packages: `ip2location` (this library, for local BIN databases) and `ip2location-io` (for the IP2Location.io web API service). Using `ip2locationio` will require an API key and make web requests, not read local BIN files.
fix
Ensure you are importing `IP2Location` if you intend to use local BIN files. If you need the web API, install and use `ip2location-io` as per its documentation.
affects: All versions
gotchaUsing the `SHARED_MEMORY` file mode for database loading can significantly speed up lookups but consumes substantial RAM. Ensure your system has sufficient memory to cache the entire database to avoid performance issues or out-of-memory errors.
fix
Monitor memory usage when using `SHARED_MEMORY`. If memory is a concern, use the default `FILE_IO` mode, or consider using a smaller database. For large databases, ensure ample RAM is available.
affects: All versions
gotchaWhile the underlying C++ library is stated to be thread-safe, the Python wrapper's thread-safety when sharing a single `IP2Location` object across multiple threads for `FILE_IO` operations is not explicitly documented. For concurrent access, creating a separate `IP2Location` instance per thread or using appropriate locking mechanisms is generally safer.
fix
For applications with multiple threads accessing the database concurrently, consider initializing a new `IP2Location` object for each thread or process to prevent potential resource conflicts or race conditions. If a single instance is shared, implement explicit synchronization (e.g., `threading.Lock`).
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'IP2Location'
The `IP2Location` Python library is either not installed, or there is a typo in the import statement.
fix
Ensure the library is installed using pip: `pip install IP2Location` and that the import statement is `import IP2Location`.
FileNotFoundError: [Errno 2] No such file or directory: 'your_database.bin'
The specified IP2Location BIN database file does not exist at the given path, or the path is incorrect.
fix
Verify that the BIN database file is present at the provided path. If it's in the same directory as your script, ensure you reference it correctly, e.g., `db = IP2Location.IP2Location('IP2LOCATION-LITE-DB1.BIN')` or provide an absolute path.
TypeError: stat: path should be string, bytes, os.PathLike or integer, not NoneType
This error typically occurs when initializing the `IP2Location` object without providing a database file path.
fix
Pass the path to your IP2Location BIN database file when creating the `IP2Location` object: `db = IP2Location.IP2Location('path/to/your/IP2LOCATION-LITE-DB1.BIN')`.
AttributeError: 'IP2LocationRecord' object has no attribute 'your_field'
You are attempting to access an attribute (e.g., city, region, isp) from an `IP2LocationRecord` object that is not available in the specific IP2Location BIN database file you are using.
fix
Ensure that the IP2Location BIN database you downloaded supports the fields you are trying to query. LITE databases might have fewer fields than commercial ones. Check the database documentation for available fields. For example, if you want ISP information, you might need a DB5 or higher.
Upgrade
Version history
8.11.0latest on PyPI · released Sep 4, 2025
Audit
Dependencies

No dependency data recorded yet.

Agent activity
13 hits · last 30 days
node
10
Resources
ip2location — pip install ip2location · libregistry