django-guardian
django-guardian is an implementation of per-object permissions on top
of Django’s authorization backend. Read an introduction to per-object permissions on djangoadvent articles.
Documentation
Online documentation is available at https://django-guardian.readthedocs.io/.
See real-world usage: Check out Who Uses Guardian to see how thousands of projects worldwide use django-guardian in production.
Contributing
Please read CONTRIBUTING.md before opening a pull request. It documents the repository's issue-first workflow, branch targeting rules, local uv setup, required test and lint commands, documentation expectations, and AI/LLM contribution policy.
If you need to report a security issue, do not open a public issue. Follow SECURITY.md and use the repository's private vulnerability reporting flow.
Installation
To install django-guardian into your project run:
uv add django-guardian
TIP: Not using a package manager like
uvorpoetryfor your django project? You probably should try them :). In the meantime,pip install django-guardianworks just fine too.
Configuration
We need to hook django-guardian into our project.
- Put
guardianinto yourINSTALLED_APPSat settings module:
INSTALLED_APPS = (
...
'guardian',
)
- Add extra authorization backend to your
settings.py:
AUTHENTICATION_BACKENDS = (
'django.contrib.auth.backends.ModelBackend',
'guardian.backends.ObjectPermissionBackend',
)
- Create
guardiandatabase tables by running:
python manage.py migrate
Usage
After installation and project hooks we can finally use object permissions with Django.
Lets start really quickly:
>>> from django.contrib.auth.models import User, Group
>>> jack = User.objects.create_user('jack', 'jack@example.com', 'topsecretagentjack')
>>> admins = Group.objects.create(name='admins')
>>> jack.has_perm('change_group', admins)
False
>>> from guardian.shortcuts import assign_perm
>>> assign_perm('change_group', jack, obj=admins)
<UserObjectPermission: admins | jack | change_group>
>>> jack.has_perm('change_group', admins)
True
Of course our agent jack here would not be able to change_group globally:
>>> jack.has_perm('change_group')
False
Admin integration
Replace admin.ModelAdmin with GuardedModelAdmin for those models
which should have object permissions support within admin panel.
For example:
from django.contrib import admin
from myapp.models import Author
from guardian.admin import GuardedModelAdmin
# Old way:
#class AuthorAdmin(admin.ModelAdmin):
# pass
# With object permissions support
class AuthorAdmin(GuardedModelAdmin):
pass
admin.site.register(Author, AuthorAdmin)
Django Unfold integration
Users of django-unfold will find that guardian is supported out of the box via a contrib module.
3 maintainers
Metadata
3 maintainers
Release files for django-guardian 3.4.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 | |
|---|---|---|---|
| django_guardian-3.4.0.tar.gz | 111.7 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| django_guardian-3.4.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 259.8 kB
Release files / django_guardian-3.4.0.tar.gz
| Download URL | django_guardian-3.4.0.tar.gz |
|---|---|
| Size | 111.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f7bd2d673c018e28970c6f98a5bdeeaaf294b9ca7726586695cff01f15db7ef0
|
|
BLAKE2b-256 checksum How to use checksums |
89c70a2cea15a432bd97fffa50b0a01be6018e30b9cdb9775ce33c41f6994fb5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 28, 2026.
Transparency logRelease files / django_guardian-3.4.0-py3-none-any.whl
| Download URL | django_guardian-3.4.0-py3-none-any.whl |
|---|---|
| Size | 148.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
73380fcf6815b1de15dea9cbfc931d20afdae30852228c9be2f286e0e84950c8
|
|
BLAKE2b-256 checksum How to use checksums |
326d518729624af9e29a7ea7f4b429ddca56fd6af3462c835b0e42b494680474
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 28, 2026.
Transparency log
