Skip to main content

Additional functionality using the GeoIP2 database.

Project description

Django GeoIP2 Extras


The master branch of this project is now Python3 only. Python2 support is restricted to the python2 branch.

Useful extras based on the django.contrib.gis.geoip2 module, using the MaxMind GeoIP2 Lite database.

The first feature in this package is a Django middleware class that can be used to add city, country level information to inbound requests.


This package wraps the existing Django functionality, and as a result relies on the same underlying requirements:

In order to perform IP-based geolocation, the GeoIP2 object requires the geoip2 Python library and the GeoIP Country and/or City datasets in binary format (the CSV files will not work!). Grab the GeoLite2-Country.mmdb.gz and GeoLite2-City.mmdb.gz files and unzip them in a directory corresponding to the GEOIP_PATH setting.

In addition, the middleware follows the ‘new’ middleware pattern, and therefore does not support Django 1.9 or below. This is a 1.10 and above package.


This package can be installed from PyPI as django-geoip2-extras:

$ pip install django-geoip2-extras

If you want to add the country-level information to incoming requests, add the middleware to your project settings. NB The GeoIP2Middleware relies on the SessionMiddleware, and must come after it:


The middleware will not be active unless you add a setting for the default GEOIP_PATH - this is the default Django GeoIP2 behaviour:

GEOIP_PATH = os.path.dirname(__file__)

NB Loading this package does not install the MaxMind database. That is your responsibility. The Country database is 2.7MB, and could be added to most project comfortably, but it is updated regularly, and keeping that up-to-date is out of scope for this project. The City database is 27MB, and is probably not suitable for adding to source control. There are various solutions out on the web for pulling in the City database as part of a CD process.


Once the middleware is added, you will be able to access City and / or Country level information on the request object:

>>> request.geo_data.ip_address
'Beverley Hills'
>>> request.geo_data.postal_code
>>> request.geo_data.region
>>> request.geo_data.country_code
>>> request.geo_data.country_name
'United States'
>>> request.geo_data.latitude
>>> request.geo_data.longitude

Missing / incomplete data will be None.

If the IP address cannot be found (e.g. ‘’), then a default ‘unknown’ country is used, with a code of ‘XX’:

>>> geo.ip_address
>>> geo.country_code
>>> geo.country_name
>>> geo.is_unknown

This prevents the middleware from re-requesting the address on each request - it effectively marks the IP as a bad address.


The project tests are run through tox.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django-geoip2-extras-1.0.tar.gz (6.7 kB view hashes)

Uploaded Source

Built Distribution

django_geoip2_extras-1.0-py3-none-any.whl (9.3 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page