python-ipware

python-ipware is a small, dependency-free Python library that extracts the best-matched client IP address from an HTTP request’s headers. Server applications commonly sit behind load balancers, reverse proxies, and CDNs (AWS ELB, NGINX, Cloudflare, Fastly, and others), which means the originating client IP is buried in headers like X-Forwarded-For rather than the socket address.

The library checks a configurable precedence list of well-known headers, parses IPv4 and IPv6 addresses, distinguishes public from private/loopback ranges, and supports trusted proxy lists and proxy counts to reduce the risk of IP address spoofing. It is framework-agnostic and serves as the standalone engine behind the popular django-ipware package.

What You Get

• Best-effort client IP extraction from a wide list of proxy/CDN headers
• IPv4 and IPv6 support via Python’s ipaddress module
• Public vs private/loopback address classification
• Configurable header precedence and left-most/right-most IP selection
• Trusted proxy list and proxy-count options to reduce spoofing risk
• A dependency-free, framework-agnostic implementation

Common Use Cases

• Getting the real client IP behind AWS ELB, NGINX, Cloudflare, or Fastly
• Powering IP-based rate limiting, logging, or geolocation in a web app
• Hardening IP resolution with trusted proxy configuration to limit spoofing
• Serving as the core engine for framework wrappers like django-ipware

Under The Hood

Architecture - The library is implemented in a single module, python_ipware/python_ipware.py, centered on an IpWare class composed from metadata and IP-handling mixins. It walks a configurable precedence tuple of ~20 known headers (X-Forwarded-For, CF-Connecting-IP, True-Client-IP, X-Real-IP, and more), splits multi-value headers, and selects the client IP from the left-most or right-most position depending on configuration and trusted-proxy settings.

Tech Stack - Pure Python with no third-party runtime dependencies, relying only on the standard library’s ipaddress and logging modules. It is fully type-annotated (ships py.typed) and built with a modern pyproject.toml.

Code Quality - The code is compact, typed, and documented with clear docstrings explaining each supported header and its origin. It includes a tests/ suite and coverage reporting, and its correctness is well-exercised through its use as the backend of django-ipware.

API Design - Usage is minimal: construct IpWare (optionally with a precedence list, proxy_count, or proxy_list) and call get_client_ip(meta) to receive the resolved IP plus a routable flag. The small surface area and sensible defaults make it easy to adopt while still exposing the knobs needed to harden against spoofing.