Install & Compatibility
Where this runs
tested against v3.0.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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.034s · 17.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.5s · import 0.032s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
IpWare
✓ from python_ipware import IpWare
✗ from ipware import IpWare
The module was renamed from `ipware` to `python_ipware` in version 2.0.0 to avoid conflicts with `django-ipware`.
This quickstart demonstrates how to instantiate `IpWare` and retrieve the client's IP address from a simulated HTTP request metadata dictionary. It also includes examples of configuring `IpWare` for environments behind trusted proxies using `proxy_count` and `proxy_list` parameters to ensure accurate IP resolution.
from python_ipware import IpWare
from pprint import pprint
# Simulate a request.META or request.environ dictionary from a web framework
# In a real web application, this dictionary would be provided by Django (request.META)
# or Flask (request.environ).
simulated_meta = {
'REMOTE_ADDR': '192.168.1.100', # Direct connection IP (e.g., last proxy)
'HTTP_X_FORWARDED_FOR': '203.0.113.45, 198.51.100.10, 192.168.1.100', # Client, Proxy1, Proxy2
'HTTP_CLIENT_IP': '203.0.113.45',
'HTTP_X_REAL_IP': '203.0.113.45',
}
# Instantiate IpWare with default configuration
ipw = IpWare()
# Get the client IP and a flag indicating if the route is trusted based on configuration
ip, trusted_route = ipw.get_client_ip(simulated_meta)
if ip:
print(f"Client IP: {ip}")
print(f"Is routable (global IP): {ip.is_global}")
print(f"Is private IP: {ip.is_private}")
print(f"Trusted route: {trusted_route}")
else:
print("Unable to determine client IP address.")
print("\n--- Custom Proxy Configuration Examples ---")
# Example with proxy_count: If your server is behind 1 known trusted proxy
# The actual client IP is assumed to be the one before the last proxy.
ipw_with_proxy_count = IpWare(proxy_count=1)
ip_pc, trusted_route_pc = ipw_with_proxy_count.get_client_ip(simulated_meta)
if ip_pc:
print(f"Client IP (with proxy_count=1): {ip_pc}")
print(f"Trusted route (with proxy_count=1): {trusted_route_pc}")
else:
print("Unable to determine client IP with proxy_count=1.")
# Example with proxy_list: If you have specific trusted proxy IPs
# Let's assume '198.51.100.10' is a known trusted proxy.
ipw_with_proxy_list = IpWare(proxy_list=['198.51.100.10'])
ip_pl, trusted_route_pl = ipw_with_proxy_list.get_client_ip(simulated_meta)
if ip_pl:
print(f"Client IP (with proxy_list=['198.51.100.10']): {ip_pl}")
print(f"Trusted route (with proxy_list=['198.51.100.10']): {trusted_route_pl}")
else:
print("Unable to determine client IP with proxy_list.")
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'ipware'
The `python-ipware` package has not been installed in the current Python environment or is not accessible on the Python path.
fixInstall the library using pip: `pip install python-ipware`
TypeError: get_client_ip() missing 1 required positional argument: 'request'
The `get_client_ip` function requires a request object (e.g., Django's `HttpRequest` or Flask's `request`) as its first argument to parse the client's IP address from headers.
fixPass the request object when calling the function: `client_ip, is_routable = get_client_ip(request)`
AttributeError: module 'ipware' has no attribute 'get_ip_address'
The function name `get_ip_address` is deprecated or incorrect for `python-ipware` version 3.0.0. The correct function name for retrieving the client IP is `get_client_ip`.
fixUpdate your code to use the current function: `from ipware import get_client_ip` and then call it as `client_ip, is_routable = get_client_ip(request)`.
ipware returns None
The `get_client_ip` function returns `None` when it cannot find a valid or routable IP address in the request headers based on the configured proxy order or trusted proxies. This often occurs in development environments, without proper `X-Forwarded-For` headers, or due to misconfigured proxy settings.
fixEnsure your request object contains relevant IP headers (e.g., `X-Forwarded-For`, `Remote-Addr`). If behind a proxy, configure the `trusted_proxies` argument for `get_client_ip` or set `IPWARE_TRUSTED_PROXIES` in Django settings (if using `django-ipware`). For local testing, you might need to simulate headers or connect from a real client.
Upgrade
Version history
3.0.0latest on PyPI · released Apr 19, 2024
Audit
Dependencies
No dependency data recorded yet.