django-tenant-users

2.2.1 verified Fri May 01 auth: no python

Extends django-tenants to add global multi-tenant user support, allowing users to belong to multiple tenants with per-tenant permissions. Current version 2.2.1, requires Python >=3.9, compatible with Django 4.2+, s. Release cadence: irregular, ~3-4 minor versions per year.

pip install django-tenant-users

Common errors

error ImportError: cannot import name 'UserTenantPermissions' from 'tenant_users.models' ↓

cause In v2.0, UserTenantPermissions was moved to tenant_users.permissions.models.

fix

Use 'from tenant_users.permissions.models import UserTenantPermissions'

error django.core.exceptions.ImproperlyConfigured: Application labels aren't unique, duplicates: tenant_users ↓

cause Having both 'django-tenant-users' and another app named 'tenant_users' in INSTALLED_APPS.

fix

Remove duplicate app entry; only include 'tenant_users' once.

error AttributeError: 'User' object has no attribute 'add_tenant' ↓

cause User model is not using TenantUserMixin from django-tenant-users.

fix

Make your user model inherit from TenantUserMixin (from tenant_users.tenants.models) and set AUTH_USER_MODEL.

Warnings

breaking In v2.0, import paths changed significantly. All models and utilities formerly in 'tenant_users.models' are now split into submodules (e.g., 'tenant_users.tenants.models', 'tenant_users.permissions.models'). ↓

fix Update imports: from tenant_users.tenants.models import TenantUserMixin, from tenant_users.permissions.models import UserTenantPermissions.

breaking provision_tenant utility function now returns the created tenant (v2.0.0). Previously it returned nothing. ↓

fix Update code that calls provision_tenant to use the returned tenant object.

gotcha UserTenantPermissions caching bug in remove_user (fixed in v2.1.2) could cause stale permissions after user removal from a tenant. ↓

fix Upgrade to v2.1.2 or later.

gotcha schema_required decorator in v2.1.2 and earlier had a bug related to connection state restoration (fixed in v2.1.3). ↓

fix Upgrade to v2.1.3 or later.

Imports

UserTenantPermissions

wrong

from tenant_users.models import UserTenantPermissions

correct

from tenant_users.permissions.models import UserTenantPermissions

UserTenantPermissions was moved to permissions submodule in v2.0

TenantUserMixin

wrong

from tenant_users.models import TenantUserMixin

correct

from tenant_users.tenants.models import TenantUserMixin

Mixin moved to tenants submodule in v2.0

AbstractBaseUserFacade

from tenant_users.tenants.models import AbstractBaseUserFacade

No common wrong import found

Quickstart

Minimal setup: add 'tenant_users' to INSTALLED_APPS and include tenant URLs.

# settings.py
INSTALLED_APPS = [
    ...
    'tenant_users',
    'django_tenants',  # required dependency
]

# urls.py
from django.urls import include, path
from tenant_users.tenants.urls import get_tenant_urls

urlpatterns = [
    path('tenant/', include(get_tenant_urls())),
]

# Create a tenant user (shell)
# from tenant_users.tenants.models import User
# u = User.objects.create_user(email='user@example.com', password='secret', is_active=True)
# tenant = Tenant.objects.create(name='My Tenant', schema_name='my_tenant')
# u.add_tenant(tenant, is_admin=True)