python-ipware

What it is and what it does

python-ipware is a lightweight utility for web applications to retrieve the client's real IP address from HTTP request headers. It handles the complexity of proxy chains and multiple header formats by checking a configurable precedence order of headers (X-Forwarded-For, HTTP_CLIENT_IP, REMOTE_ADDR, and others) and returning an IPv4Address or IPv6Address object with properties like is_global, is_private, and is_loopback.

The package is designed for Django, Flask, and similar frameworks where the request object is available. It supports proxy validation through proxy_list (trusted proxy IP prefixes) and proxy_count (expected number of proxies in the chain) parameters to help filter spoofed requests. The documentation emphasizes that IP spoofing cannot be completely prevented and recommends using the package only as an additional security layer alongside firewall rules, not as a primary defense mechanism.

Use it for:

• Log or track client IP addresses in web application request handlers for auditing or analytics.
• Implement geolocation-based features by extracting the real client IP behind load balancers or CDNs.
• Validate incoming requests against IP allowlists or blocklists in security middleware.
• Detect and filter requests from known proxy or VPN services by examining trusted proxy chains.
• Attach client IP metadata to user sessions or API calls for debugging and monitoring.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Extracts a client's IP address from web request headers, handling proxies and multiple header formats to identify the originating client in server applications.

Yes, if you need straightforward client IP extraction in a web framework and are willing to accept dormant maintenance. The package is stable, has no dependencies, and handles the common proxy scenarios well. However, do not rely on it as a primary security mechanism—always pair it with firewall rules and validate proxy chains carefully if IP spoofing is a concern in your threat model.

Install

python-ipware on PyPI

pip install python-ipware

uv add python-ipware

poetry add python-ipware

Installing python-ipware

Before you install

Low friction: pure Python wheel with no runtime dependencies. Dormant maintenance status (last commit April 2024, 847 days since release) means no active development, but the codebase is stable and the package supports current Python versions (3.7–3.12).

License in practice

MIT license (permissive) places no restrictions on use, modification, or distribution in proprietary or open-source projects.

Quickstart

pip install python-ipware

from python_ipware import IpWare

ipw = IpWare()
ip, trusted_route = ipw.get_client_ip(meta=request.META)  # Django
# or: ipw.get_client_ip(meta=request.environ)  # Flask

Requires a request object with META (Django) or environ (Flask) attributes; IP spoofing is possible without additional proxy validation—use proxy_list or proxy_count parameters to verify trusted proxies.

Verify before relying

• Whether the package handles IPv6 addresses correctly in all proxy scenarios.
• Performance impact when checking against large proxy lists or custom header precedence orders.
• How the package behaves with non-standard or malformed X-Forwarded-For headers.

Package facts

Evidence: python_ipware-3.0.0-py3-none-any.whl

Tags

More WWW/HTTP packages