Django IPware

7.0.1 · active · verified Thu Apr 09

A Django application to retrieve a user's IP address. It aims to provide the best attempt to get the client's IP while handling scenarios involving proxy servers and load balancers. `django-ipware` is a wrapper using `python-ipware` under the hood since version 6.0.0. The current version is 7.0.1, released on April 19, 2024, indicating active development and a regular release cadence with updates to align with new Django and Python versions.

Common errors

```
ModuleNotFoundError: No module named 'ipware'
```
cause The 'django-ipware' package has not been installed in the active Python environment or is not accessible.

fix Install the package using pip: `pip install django-ipware`
```
client_ip is None (from get_client_ip) OR ip_address is None OR returns '127.0.0.1' (or local IP)
```
cause The library is unable to reliably determine the client's public IP address, often because the application is behind proxy servers or load balancers, and `django-ipware` is not configured to correctly interpret the relevant HTTP headers. This can also occur when testing in a local development environment.

fix Configure `proxy_count`, `proxy_trusted_ips`, or `request_header_order` in the `get_client_ip` function to instruct `ipware` how to correctly parse IP addresses from proxy headers. For example: `client_ip, is_routable = get_client_ip(request, proxy_count=1, request_header_order=('X_FORWARDED_FOR', 'REMOTE_ADDR'))`
```
from django_ipware import get_client_ip
```
cause Developers often mistakenly attempt to import `get_client_ip` from `django_ipware` (the package name) instead of the correct top-level module `ipware`.

fix The correct import statement is `from ipware import get_client_ip`

Warnings

gotcha There is no perfect out-of-the-box solution against IP Address Spoofing. `django-ipware` makes the best attempt but should be used only as a complement to other firewall and security measures.
Fix: Implement additional security measures (firewalls, WAFs) and utilize `proxy_trusted_ips` or `proxy_count` arguments if behind known proxies to improve accuracy. Always validate IP addresses for security-critical operations.
breaking Prior to version 6.0.0, `django-ipware` was a standalone package. From version 6.0.0 onwards, it became a wrapper around the `python-ipware` package. While the primary `get_client_ip` import path remains stable, internal workings and advanced configurations (especially for direct `python-ipware` usage) might differ.
Fix: Review `django-ipware` and `python-ipware` documentation for specific API changes if upgrading from versions older than 6.0.0, especially if customizing IP resolution logic beyond basic `get_client_ip` calls. Ensure `python-ipware` is considered a core dependency for recent versions.
gotcha Incorrect IP address resolution behind proxy servers (e.g., load balancers, CDNs). Without proper configuration, `django-ipware` might return the proxy's IP address instead of the actual client's IP.
Fix: If your Django server is behind proxies, configure `get_client_ip(request, proxy_count=N)` with the correct number of proxies or `get_client_ip(request, proxy_trusted_ips=['IP_1', 'IP_2'])` with known trusted proxy IP ranges. Customize `IPWARE_META_PRECEDENCE_ORDER` in settings if non-standard HTTP headers are used.
deprecated Some integrating packages (e.g., `django-axes` versions 6+) have made `django-ipware` an optional dependency and renamed their internal settings related to IPware. This indicates a shift towards more explicit dependency management and configuration in ecosystem partners.
Fix: If using `django-ipware` with `django-axes` or similar packages, ensure `django-ipware` is explicitly installed (`pip install django-ipware`) and review the integrating library's documentation for updated configuration settings (e.g., `AXES_IPWARE_PROXY_ORDER` instead of `AXES_PROXY_ORDER` in `django-axes`).

Install

pip install django-ipware Install latest version

Imports

get_client_ip
wrong:
```
from django_ipware import get_client_ip
```
correct:
```
from ipware import get_client_ip
```
The main function `get_client_ip` is directly importable from the `ipware` module, not `django_ipware`.

Quickstart

A simple Django view demonstrating how to retrieve the client's IP address using `get_client_ip`. It returns the IP address and a boolean indicating if it's publicly routable. Remember to pass the `request` object.

from django.http import HttpRequest, JsonResponse
from ipware import get_client_ip

def my_view(request: HttpRequest):
    client_ip, is_routable = get_client_ip(request)

    if client_ip is None:
        # Unable to get the client's IP address
        return JsonResponse({'error': 'Unable to determine client IP'}, status=400)
    else:
        # We got the client's IP address
        ip_info = {
            'ip_address': str(client_ip),
            'is_publicly_routable': is_routable
        }
        return JsonResponse(ip_info)

view raw JSON →