Install & Compatibility
Where this runs
tested against v1.9.5 · 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.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 18MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 3.3s · import 0.000s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
VERSION
✓ from impersonate import VERSION
✗ from impersonate.middleware import ImpersonateMiddleware
get_version
✓ from impersonate import get_version
✗ from impersonate.middleware import ImpersonateMiddleware
To quickly set up django-impersonate, add `impersonate` to `INSTALLED_APPS`, integrate `ImpersonateMiddleware` into your `MIDDLEWARE` stack (crucially, after `SessionMiddleware` and `AuthenticationMiddleware`), and include `impersonate.urls` in your project's `urls.py`. You can then use the provided views or template tags to initiate and end impersonation sessions. The quickstart demonstrates basic setup and how to include the URLs and middleware, along with template tag usage.
# settings.py
INSTALLED_APPS = [
# ...
'impersonate',
]
MIDDLEWARE = [
# ...
'django.contrib.sessions.middleware.SessionMiddleware',
'django.contrib.auth.middleware.AuthenticationMiddleware',
'impersonate.middleware.ImpersonateMiddleware', # Must be AFTER Session and Auth middleware
# ...
]
# urls.py
from django.urls import path, include
from django.contrib import admin
urlpatterns = [
path('admin/', admin.site.urls),
path('impersonate/', include('impersonate.urls')),
# ... your other urls
]
# In a template (e.g., base.html) to show an impersonation link:
# {% load impersonate_tags %}
# {% if user.is_authenticated and user.is_superuser %}
# {% if impersonate %} # 'impersonate' variable comes from context processor
# <a href="{% url 'impersonate-leave' %}">Leave Impersonation</a>
# {% else %}
# <a href="{% url 'impersonate-start' user_id=1 %}">Impersonate User (ID 1)</a> # Replace 1 with actual user ID
# <a href="{% url 'impersonate-start' username='testuser' %}">Impersonate User (username testuser)</a>
# {% endif %}
# {% endif %}
Debug
Known issues
breakingPrior to version 1.7.0, django-impersonate used `django.conf.urls.url` for its URL patterns. Projects upgrading from older Django versions (pre-2.0) that also used `url()` in their project's `urls.py` would have been compatible. From 1.7.0 onwards, it uses `django.urls.path`. If your project's `urls.py` still uses `url()` and you upgrade django-impersonate to 1.7.0+, you might face `NoReverseMatch` errors or URL resolution issues if not updated to `path()`.fixEnsure your project's `urls.py` uses `django.urls.path` for including `impersonate.urls` and any other patterns, especially if your Django version is 2.0 or newer. Example: `path('impersonate/', include('impersonate.urls'))`. affects: <1.7.0 to 1.7.0+
breakingIn version 1.8.0, the `login_url` used for redirection after an unsuccessful impersonation attempt changed from a hardcoded `/accounts/login/` to dynamically using `django.conf.settings.LOGIN_URL`. If your project previously relied on the hardcoded path and did not have `LOGIN_URL` defined, this might cause unexpected redirection behavior.fixEnsure `settings.LOGIN_URL` is correctly configured in your Django project's `settings.py` to point to your desired login page, or define it if it was previously absent.
affects: <1.8.0 to 1.8.0+
gotchaThe `ImpersonateMiddleware` must be placed correctly in your `MIDDLEWARE` setting. It relies on `SessionMiddleware` and `AuthenticationMiddleware` to function correctly, meaning it must appear *after* both of them in the `MIDDLEWARE` list.fixVerify that your `settings.MIDDLEWARE` list has `django.contrib.sessions.middleware.SessionMiddleware` and `django.contrib.auth.middleware.AuthenticationMiddleware` listed *before* `impersonate.middleware.ImpersonateMiddleware`.
affects: All versions
gotchaImpersonation links or buttons might not appear, or the impersonation functionality might not work as expected, due to incorrect user permissions or configuration. By default, only superusers can impersonate. You can change this behavior with `IMPERSONATE_REQUIRE_SUPERUSER` or `IMPERSONATE_CUSTOM_USER_QUERY`.fixEnsure the user attempting to impersonate is a superuser (or meets criteria defined by `IMPERSONATE_CUSTOM_USER_QUERY`). Check your `settings.py` for `IMPERSONATE_REQUIRE_SUPERUSER` (defaults to `True`) and `IMPERSONATE_CUSTOM_USER_QUERY` if you have custom permission logic.
affects: All versions
Upgrade
Version history
1.9.5latest on PyPI · released Apr 5, 2025
Audit
Dependencies
DjangorequiredThis is a Django application and requires Django to run. Compatible with Django 3.2 to 5.0.