Skip to content
Extends Django's "cached_db" session backend (Sessions store IP, User Agent, and foreign key to User)
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
LICENSE.txt rename LICENSE to LICENSE.txt Jan 20, 2018


django-qsessions is a session backend for Django that extends Django's cached_db session backend and Session model to add following features:

  • Sessions have a foreign key to User
  • Sessions store IP and User Agent


Here is a brief comparison between Django's session backends (db, cache, cached_db), django-user-sessions, and django-qsessions.

  db cache cached_db django-user-sessions django-qsessions
Better Performance   ✔✔  
Foreign Key to User      
Store IP and User Agent      


Python version Django versions
3.7 2.0, 2.1, 2.2
3.6 1.10, 1.11, 2.0, 2.1, 2.2
3.5 1.10, 1.11, 2.0, 2.1, 2.2
3.4 1.10, 1.11, 2.0
2.7 1.10, 1.11


Please note that if your system is in production and there are lots of active sessions using another session backend, you need to migrate them manually. We have no migration script.

  1. First, make sure you've configured your cache. If you have multiple caches defined in CACHES, Django will use the default cache. To use another cache, set SESSION_CACHE_ALIAS to the name of that cache.

  2. Install the latest version from PyPI:

    pip install django-qsessions
  3. In settings:

    • In INSTALLED_APPS replace 'django.contrib.sessions' with 'qsessions'.
    • In MIDDLEWARE or MIDDLEWARE_CLASSES replace 'django.contrib.sessions.middleware.SessionMiddleware' with 'qsessions.middleware.SessionMiddleware'.
    • Set SESSION_ENGINE to 'qsessions.backends.cached_db'.
  4. Run migrations to create qsessions.models.Session model.

    python migrate qsessions

For enabling location detection using GeoIP2 (optional):

  1. Install geoip2 package:

    pip install geoip2
  2. Set GEOIP_PATH to a directory for storing GeoIP2 database.

  3. Run the following command to download latest GeoIP2 database. You can add this command to a cron job to update GeoIP2 DB automatically.

    python download_geoip_db


django-qsessions has a custom Session model with following fields: user, user_agent, created_at, updated_at, ip.

Getting a user's sessions:


Deleting a session:

# Deletes session from both DB and cache

Logout a user:


Session creation time (user login time):

>>> session.created_at
datetime.datetime(2018, 6, 12, 17, 9, 17, 443909, tzinfo=<UTC>)

IP and user agent:

>>> session.ip
>>> session.user_agent
'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/65.0.3325.181 Safari/537.36'

And if you have configured GeoIP2, you can call .location(), .location_info():

>>> session.location()
'Tehran, Iran'

>>> session.location_info()
{'city': 'Tehran', 'continent_code': 'AS', 'continent_name': 'Asia', 'country_code': 'IR', 'country_name': 'Iran', 'time_zone': 'Asia/Tehran', ...}

Admin page:


  • session.updated_at is not the session's last activity. It's updated each time the session object in DB is saved. (e.g. when user logs in, or when ip, user agent, or session data changes)

Why not django-user-sessions?

django-user-sessions has the same functionality, but it's based on db backend. Using a cache will improve performance.

We got ideas and some codes from django-user-sessions. Many thanks to Bouke Haarsma for writing django-user-sessions.


  • Install development dependencies in your virtualenv with pip install -e '.[dev]'
  • Run tests with coverage using py.test --cov .


  • Write better documentation.
    • Explain how it works (in summary)
    • Add more details to existing documentation.
  • Write more tests
  • Performance benchmark (and compare with Django's cached_db)

Contributions are welcome!



You can’t perform that action at this time.