django-debug-toolbar-hijack
A django-debug-toolbar panel for impersonating users with django-hijack.
The Hijack panel lets you switch to another account straight from the debug toolbar:
- It lists the users you may hijack, each with a one-click Hijack button. The list is capped (100 users by default), and the nav subtitle shows how many users are available, for example "12 hijackable" or "100+ hijackable".
- A search box finds users past that cap. It searches the same way the user model's Django admin does.
- While you're impersonating someone, it shows who you're working as, the hijack history, and a Release hijack button.
The buttons POST to django-hijack's own acquire and release views, so hijack's permission checks, signals and session handling all still apply.
Installation
pip install django-debug-toolbar-hijack
Or with uv:
uv add django-debug-toolbar-hijack
This installs Django, django-debug-toolbar and django-hijack if they aren't already installed.
Setup
First set up django-debug-toolbar and django-hijack as their docs describe. Then:
-
Add the app to
INSTALLED_APPS, afterdebug_toolbarandhijack:INSTALLED_APPS = [ # ... "debug_toolbar", "hijack", "debug_toolbar_hijack", ]
-
Add the panel to
DEBUG_TOOLBAR_PANELS. SettingDEBUG_TOOLBAR_PANELSreplaces the toolbar's default panel list, so start from the defaults:from debug_toolbar.settings import PANELS_DEFAULTS DEBUG_TOOLBAR_PANELS = [ *PANELS_DEFAULTS, "debug_toolbar_hijack.panels.HijackPanel", ]
-
Include hijack's URLs. This is required: the panel's forms POST to
hijack:acquireandhijack:release. The debug toolbar's URLs must be included too, since the search endpoint is served under them:from debug_toolbar.toolbar import debug_toolbar_urls from django.urls import include, path urlpatterns = [ # ... path("hijack/", include("hijack.urls")), *debug_toolbar_urls(), ]
django-hijack also needs hijack.middleware.HijackUserMiddleware in MIDDLEWARE; see its docs.
Compatibility
| Package | Supported versions |
|---|---|
| Python | 3.10, 3.11, 3.12, 3.13, 3.14 |
| Django | 5.2 (Python 3.10+), 6.0 (Python 3.12+) |
| django-debug-toolbar | 5.1.0 or later |
| django-hijack | 3.7 or later |
CI tests every supported Python and Django combination, plus a run against the lowest allowed versions of each dependency.
Settings
HIJACK_USER_QUERYSET
Which users the panel lists and searches. It is a dotted path to a callable, or the callable itself, with this signature:
def my_queryset(*, user: AbstractBaseUser | AnonymousUser) -> QuerySet: ...
user is the current (hijacking) user. The panel sorts the result by the user model's USERNAME_FIELD, so the callable doesn't need to order it.
The default is debug_toolbar_hijack.users.superusers_only. It mirrors django-hijack's default permission check, hijack.permissions.superusers_only: an active superuser sees every other active user, and everyone else sees nobody. Unlike hijack's check, it leaves out the current user, since hijacking yourself is never useful from a list.
If you use hijack's superusers_and_staff permission check, a matching queryset looks like this:
# myproject/hijack.py
from django.contrib.auth import get_user_model
def superusers_and_staff(*, user):
"""Superusers see every other active user; staff see active non-staff users."""
User = get_user_model()
if not user.is_active:
return User.objects.none()
users = User.objects.filter(is_active=True).exclude(pk=user.pk)
if user.is_superuser:
return users
if user.is_staff:
return users.filter(is_staff=False, is_superuser=False)
return User.objects.none()
# settings.py
HIJACK_PERMISSION_CHECK = "hijack.permissions.superusers_and_staff"
HIJACK_USER_QUERYSET = "myproject.hijack.superusers_and_staff"
The list is display only. Clicking Hijack POSTs to hijack's acquire view, which still enforces HIJACK_PERMISSION_CHECK. If the queryset shows users that the permission check rejects, those buttons fail; if it leaves out users the check allows, you can't reach them from the panel. Keep the two settings in sync.
Search
The search box queries a JSON endpoint that the panel adds under the debug toolbar's URLs. It returns 404 whenever the toolbar is hidden (SHOW_TOOLBAR_CALLBACK), and no results for anonymous users. Results always come from HIJACK_USER_QUERYSET, so search never shows a user the list wouldn't, and they're capped at the same user_limit.
Matching works like the Django admin's user changelist:
- When
django.contrib.adminis installed and the user model is registered on the admin site withsearch_fields, the search calls thatModelAdmin'sget_search_results(). The^,=and@prefixes onsearch_fields,get_search_fields()overrides and customget_search_results()overrides all apply. - Otherwise, it does a case-insensitive substring match on the user model's
USERNAME_FIELDand its email field, if it has one.
The admin site defaults to django.contrib.admin.site. If your user admin is registered on a custom AdminSite, set the panel's admin_site as shown below.
Customizing the panel
user_limit and admin_site are attributes on the panel class. Change them by subclassing it and listing your subclass in DEBUG_TOOLBAR_PANELS instead of HijackPanel:
# myproject/panels.py
from debug_toolbar_hijack.panels import HijackPanel
class MyHijackPanel(HijackPanel):
# The most users to list and to return from a search (default 100).
user_limit = 25
# A dotted path to the AdminSite whose user ModelAdmin drives the search,
# or the AdminSite itself (default "django.contrib.admin.site").
admin_site = "myproject.admin.site"
# settings.py
DEBUG_TOOLBAR_PANELS = [
*PANELS_DEFAULTS,
"myproject.panels.MyHijackPanel",
]
Development
Tools and Python are managed with mise, the environment with uv, and checks with hk. mise syncs .venv with uv sync whenever pyproject.toml or uv.lock change.
mise install
mise run ci
mise run ci runs the lint, typecheck and test tasks. The others are:
| Task | What it does |
|---|---|
mise run lint |
Every hk check: ruff, ruff format, mypy, whitespace, Markdown |
mise run fix |
Every hk fixer |
mise run typecheck |
mypy in strict mode with django-stubs |
mise run test |
pytest with coverage |
mise run test:lowest |
pytest against the lowest allowed versions of the direct dependencies |
mise run build |
Build the sdist and wheel into dist/ |
mise run release:prepare |
Bump the version and update the changelog on a branch, then open a release PR; see Releasing |
mise run release:tag |
Tag the merged release and optionally push the tag; see Releasing |
Demo server
tests/demo is a small site for trying the panel by hand. It migrates a local SQLite database, seeds a superuser plus 151 other users (more than the default cap, so search has something to find), and starts the development server:
.venv/bin/python tests/demo/manage.py demo
Every request is logged in as the demo superuser, so never run it anywhere but your own machine. Claude Code users can also start it from .claude/launch.json as hijack-demo.
Releasing
Releases publish to PyPI from GitHub Actions with trusted publishing, so no API token is stored in GitHub.
One-time setup, before the first release:
- On PyPI, add a GitHub trusted publisher (under your account's publishing settings before the project exists, or the project's Settings → Publishing after) with project name
django-debug-toolbar-hijack, this repository's owner and name, workflowrelease.yml, and environmentpypi. - On GitHub, create an environment named
pypiunder Settings → Environments. Optionally add required reviewers and restrict it tov*tags.
main is protected: changes land only through pull requests that pass CI. So a release takes two steps, a release PR and then a tag.
1. Open the release PR. From an up-to-date, clean main with the changes listed under [Unreleased] in CHANGELOG.md:
mise run release:prepare --dry-run beta
mise run release:prepare beta
The argument is an explicit version (such as 0.1.0b2) or a uv version --bump keyword: major, minor, patch, stable, alpha, beta, rc, post or dev. The task:
- Refuses to run unless the working tree is clean, the branch is
mainand it matchesorigin/main, the new version is newer than the current one, and neither the tagvXnor the branchrelease/vXexists locally or onorigin. - Builds the new
CHANGELOG.md: the[Unreleased]entries move under a dated heading for the new version and the compare links are updated. It refuses if[Unreleased]is empty, unless the new version is a pre-release that follows a pre-release of the same version (such as0.1.0b1→0.1.0b2); that release is noted as having no changes. - Runs
mise run ci. - Creates the branch
release/vXfrommain, bumps the version inpyproject.tomlanduv.lockwithuv version, writes the changelog and commitsRelease vX. - Pushes the branch and opens a PR to
mainwithgh pr create. The PR body is the new changelog section and the next step.
--no-pr stops after the local commit and prints the push and gh pr create commands. --dry-run runs the checks, then shows every other step, the new version, the CHANGELOG.md diff and the PR body without changing anything. All checks run before anything is modified. The task never pushes to main and never creates a tag.
2. Tag the release. Once the PR is merged, update main and tag it:
git switch main && git pull --ff-only
mise run release:tag --dry-run
mise run release:tag --push
The task refuses to run unless the working tree is clean and main matches origin/main. It reads the version with uv version --short, checks that CHANGELOG.md has a section for it and that the tag vX doesn't exist locally or on origin, then creates the annotated tag vX.
The tag goes on the commit that set the version on main (the merge of the release PR), not necessarily HEAD. If other PRs were merged after the release PR, the task warns and lists them: they aren't part of the release, so the published package matches what the release PR and its changelog describe.
Without --push, the task prints the push command instead of running it. --push pushes only the tag (git push origin refs/tags/vX), which starts the Release workflow: it checks that the tag matches the pyproject.toml version, then builds the sdist and wheel and publishes them to PyPI.
License
BSD-3-Clause. See LICENSE.
Metadata
Release files for django-debug-toolbar-hijack 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| django_debug_toolbar_hijack-0.1.0.tar.gz | 15.5 kB | Without provenance | Details for django_debug_toolbar_hijack-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| django_debug_toolbar_hijack-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for django_debug_toolbar_hijack-0.1.0-py3-none-any.whl |
Total release size: 34.0 kB
Release files / django_debug_toolbar_hijack-0.1.0.tar.gz
| Download URL | django_debug_toolbar_hijack-0.1.0.tar.gz |
|---|---|
| Size | 15.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d9266806c192a4fe74960a19c3319d7c7926c44835f8aced54f9a273a7546ff3
|
|
BLAKE2b-256 checksum How to use checksums |
7e5bd7dffe7c03df67c525eff568e89862649a361ecee78c064c92dd6f8861e3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / django_debug_toolbar_hijack-0.1.0-py3-none-any.whl
| Download URL | django_debug_toolbar_hijack-0.1.0-py3-none-any.whl |
|---|---|
| Size | 18.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c8dae9a795bcd5fb578e9773ad8b7a1a7c68e60ea1baa1da6f53f30c26464af5
|
|
BLAKE2b-256 checksum How to use checksums |
c974fcd08704d0102b908a18b832dd015817238234b8464e4f0aa46e10217cf5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for django-debug-toolbar-hijack 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.