---
id: ip3country
version: "0.4.0"
license: ISC
license_treatment: permissive
maintenance: active
---

# ip3country — A zero-dependency, local, fast, tiny ip-address to country lookup

License: permissive · Maintenance: active · Downloads: 8.6M/mo

## What it is and what it does

ip3country is a minimal IP-to-country lookup library designed for speed and size. It maps IP addresses to their ISO 3166-1 alpha-2 country codes using a compacted database derived from IP2Location LITE data, all in under 500KB with zero external dependencies. The library supports both string and numeric IP address formats and is built for applications that need fast, local country detection without the overhead of larger geolocation libraries.

The package is actively maintained and ranks in the top 5000 PyPI packages by download volume. It was created at Statsig to power country-level feature flag rollouts and A/B tests, making it suitable for any application requiring lightweight, offline country-level IP geolocation without network calls or large data files.

Use it for:

- Evaluate location-based feature flags or A/B test conditions based on user IP country.
- Filter or route traffic by country in a lightweight, self-contained service.
- Add country-level analytics or logging to requests without external API calls.
- Implement country-based access controls or compliance checks in edge functions.
- Populate country metadata in high-volume logging pipelines where size and speed matter.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Looks up the ISO 3166-1 alpha-2 country code for an IP address using a compacted local database, with zero runtime dependencies and a footprint under 500KB.

Yes. Zero dependencies, active maintenance, permissive license, and a proven track record of high download volume make this a reliable choice for any application needing fast, local IP-to-country lookup. The small footprint and offline operation are significant advantages over larger geolocation libraries. Verify that IP2Location LITE's accuracy meets your geographic coverage needs before deploying.

## Install

pip install ip3country
uv add ip3country
poetry add ip3country

## Installing ip3country

Before you install: Installs cleanly with no runtime dependencies. Actively maintained with a recent commit on 2026-08-12 and steady releases since first_release 2021-10-04.

License in practice: Licensed under ISC (permissive), allowing commercial and private use with minimal restrictions. Attribution to IP2Location LITE data is required per the CCA license of the underlying database.

Quickstart:

pip install ip3country

from ip3country import CountryLookup

lookup = CountryLookup()
print(lookup.lookupStr("123.45.67.8"))  # 'KR'

Verify before relying:

- Whether accuracy for country-level lookups meets your specific use case (IP2Location LITE accuracy varies by region and IP type).
- Whether the compacted database is updated regularly and how to refresh it if needed.

## Package facts

- License: ISC (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 8.6M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

ip address to country code lookup, geoip country detection, lightweight ip geolocation, local ip country mapping, fast country code from ip, offline ip geolocation, minimal ip2country library, geolocation, ip-lookup, lightweight

[View on SkillFed](https://skillfed.io/packages/ip3country) · [View on PyPI](https://pypi.org/project/ip3country/)