https://github.com/django-guardian/django-guardian
Per object permissions for Django
https://github.com/django-guardian/django-guardian
hacktoberfest
Last synced: 6 months ago
JSON representation
Per object permissions for Django
- Host: GitHub
- URL: https://github.com/django-guardian/django-guardian
- Owner: django-guardian
- License: other
- Created: 2010-06-04T23:15:37.000Z (over 15 years ago)
- Default Branch: next
- Last Pushed: 2025-05-07T19:39:24.000Z (6 months ago)
- Last Synced: 2025-05-12T02:51:14.619Z (6 months ago)
- Language: Python
- Homepage: https://django-guardian.readthedocs.io/
- Size: 1.84 MB
- Stars: 3,728
- Watchers: 77
- Forks: 577
- Open Issues: 129
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
- -awesome-django - django-guardian - Per object permissions in Django. (Third-Party Packages / General)
- awesome-starts - django-guardian/django-guardian - Per object permissions for Django (Python)
- awesome-django - django-guardian - Implementation of per object permissions as authorization backend. (Authorization)
- awesome-django - django-guardian - Implementation of per object permissions as authorization backend. (Authorization)
- awesome-django - django-guardian - Per object permissions in Django. (Third-Party Packages / Permissions)
- awesome-django-security - Django Guardian - object permissions on top of Django's authorization backend. (Libs / Permissions management)
- best-django-resource - django-guardian - Adds per-object permissions for Django's built-in authentication system. (Security)
- awesome-django-cn - django-guardian, star:1412 - 实现对象级别的权限，来用作授权后端。 (授权)
- awesome-django-admin-interface - django-guardian - Implements per-object permissions for Django models. (Best Django Admin Interface Resources / **🖥️ Django REST Framework & API-Related Packages**)
- awesome-django-admin-interface - django-guardian - Implements per-object permissions for Django models. (Best Django Admin Interface Resources / **🖥️ Django REST Framework & API-Related Packages**)
- best-of-web-python - GitHub - 8% open · ⏱️ 24.09.2025): (Authorization & Authentication)
README
# django-guardian
[](https://github.com/django-guardian/django-guardian/actions/workflows/tests.yml)
[](https://pypi.python.org/pypi/django-guardian)
[](https://pypi.python.org/pypi/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](https://github.com/djangoadvent/djangoadvent-articles/blob/master/1.2/06_object-permissions.rst).
## Documentation
Online documentation is available at [https://django-guardian.readthedocs.io/](https://django-guardian.readthedocs.io/).
## Installation
To install `django-guardian` into your project run:
```bash
uv add django-guardian
```
> **TIP**: Not using a package manager like `uv` or `poetry` for your django project? You probably should try them :). In the meantime, `pip install django-guardian` works just fine too.
## Configuration
We need to hook `django-guardian`` into our project.
1. Put `guardian` into your `INSTALLED_APPS` at settings module:
```python
INSTALLED_APPS = (
...
'guardian',
)
```
2. Add extra authorization backend to your `settings.py`:
```py
AUTHENTICATION_BACKENDS = (
'django.contrib.auth.backends.ModelBackend',
'guardian.backends.ObjectPermissionBackend',
)
```
3. Create `guardian` database 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:
```py
>>> 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)
>>> jack.has_perm('change_group', admins)
True
```
Of course our agent jack here would not be able to _change_group_ globally:
```py
>>> 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:
```py
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`](https://unfoldadmin.com/) will find that `guardian` is [supported out of the box via a `contrib` module](https://unfoldadmin.com/docs/integrations/django-guardian/).