Django Smart Ratelimit

A high-performance rate limiting library for Django. Protects your APIs from abuse with atomic Redis operations, multiple algorithms, circuit breaking, and full async support -- optimized for distributed systems.

Key Features

Sync and Async -- Dual-mode support with native @ratelimit and @aratelimit decorators
Enterprise Reliability -- Built-in circuit breaker, automatic failover, and fail-open strategies
Multiple Algorithms -- Token bucket, sliding window, fixed window, and leaky bucket
Flexible Backends -- Redis (recommended), async Redis, in-memory, MongoDB, Memcached, Django ORM (database), or custom backends
Precise Control -- Rate limit by IP, user, header, or any custom callable
Shadow Mode -- Evaluate and log decisions without enforcing them for safe, zero-risk rollouts (docs)
Cost-Based (Weighted) Limiting -- Charge expensive requests more of the budget via a per-request cost (docs)
CIDR Allow/Deny Lists -- IPv4/IPv6 allowlists and denylists from inline CIDRs, files, or URL feeds (docs)
DRF Throttle Adapter -- Drop-in BaseThrottle classes for Django REST Framework (docs)
Observability -- Prometheus /metrics, OpenTelemetry spans and metrics, and structured JSON logging (docs)
Type-Safe Enums -- Optional Algorithm and RateLimitKey enums for autocomplete and typo-proof config
Configurable Proxy Trust -- RATELIMIT_TRUSTED_PROXIES for spoof-resistant client IP extraction behind load balancers (new in v3.1)
Adaptive Rate Limiting -- Dynamic limits based on CPU, memory, latency, time-of-day, and custom load indicators
Dynamic Rules -- Define and change limits at runtime from the Django admin, no redeploy (docs)
User-Aware Limiting -- Per-user tiers, Django-group mapping, temporary overrides, and API-key tiers (docs)
Analytics & Alerting -- Event logging, a staff dashboard, offender reports, and email/webhook alerts (docs)
Geographic & Multi-Tenant -- Per-country rates and per-tenant quotas (geo, tenants)
GraphQL -- Graphene middleware and a Strawberry extension with query-complexity weighting (docs)

Quick Start

Installation

pip install django-smart-ratelimit[redis]

Basic Usage

from django_smart_ratelimit import ratelimit

@ratelimit(key='ip', rate='5/m', block=True)
def login_view(request):
    return authenticate(request)

Keys and algorithms accept plain strings, or the RateLimitKey and Algorithm enums if you prefer autocomplete and a typo-proof contract. The two are interchangeable:

from django_smart_ratelimit import ratelimit
from django_smart_ratelimit.enums import Algorithm, RateLimitKey

@ratelimit(key=RateLimitKey.USER_OR_IP, rate='5/m', algorithm=Algorithm.TOKEN_BUCKET)
def login_view(request):
    return authenticate(request)

Async Support

from django_smart_ratelimit import aratelimit

@aratelimit(key='user', rate='100/h', block=True)
async def api_view(request):
    return await process(request)

Class-Based Views

Apply the decorator to a method with Django's method_decorator:

from django.utils.decorators import method_decorator
from django.views import View

from django_smart_ratelimit import ratelimit


class LoginView(View):
    @method_decorator(ratelimit(key='ip', rate='5/m', block=True))
    def post(self, request):
        return authenticate(request)

Configuration

Add to your Django settings:

RATELIMIT_BACKEND = 'redis'
RATELIMIT_REDIS = {'host': 'localhost', 'port': 6379, 'db': 0}
# Or point at a Redis URL instead of host/port:
# RATELIMIT_REDIS = {'url': 'redis://localhost:6379/0'}

# Optional: enable structured logging
RATELIMIT_LOGGING = {
    'ENABLED': True,
    'FORMAT': 'json',  # "json" or "text"
}

# Optional: enable Prometheus metrics
RATELIMIT_PROMETHEUS = {
    'ENABLED': True,
}

If RATELIMIT_BACKEND is unset, the in-memory backend is used by default.

Documentation

Full documentation is hosted on Read the Docs:

Topic	Description
Full Documentation	Start here for the complete guide
Installation	Optional extras: Redis, MongoDB, DRF, Prometheus, OpenTelemetry
Decorator API	Every argument, including shadow mode and cost-based limiting
Migration Guide	Steps for upgrading from `django-ratelimit`
Algorithms	Deep dive into token bucket, sliding window, and more
Backends	Redis, async Redis, memory, MongoDB, and the Django ORM database backend
Configuration	Advanced settings, CIDR lists, proxy trust, and circuit breakers
Dynamic Rules	Runtime, admin-editable rate-limit rules
User Tiers	Tiers, groups, per-user overrides, and API-key tiers
Analytics	Event logging, dashboard, offender reports, and alerting
Geographic / Multi-Tenant / GraphQL	Per-country, per-tenant, and GraphQL limiting
Deployment	Running in production behind proxies and load balancers
Design Philosophy	Architecture decisions and comparison with alternatives

Compatibility

	Supported Versions
Python	3.9, 3.10, 3.11, 3.12, 3.13, 3.14
Django	3.2, 4.2, 5.0, 5.1, 5.2, 6.0

Contributing

Contributions are welcome. Please see CONTRIBUTING.md for details on how to submit pull requests, report issues, and set up your development environment.

Community and Support

GitHub Discussions -- Ask questions and share ideas
Issues -- Report bugs
Changelog -- Release history

License

This project is licensed under the MIT License. See the LICENSE file for details.

Metadata

Release files for django-smart-ratelimit 4.12.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for django-smart-ratelimit 4.12.1
File	Size	Uploaded
django_smart_ratelimit-4.12.1.tar.gz	518.4 kB	Jun 5, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for django-smart-ratelimit 4.12.1
File	Interpreter	ABI	Platform	Reset
django_smart_ratelimit-4.12.1-py3-none-any.whl 229.5 kB Jun 5, 2026	Python 3	none	any	Details

Total release size: 747.8 kB

Release files / django_smart_ratelimit-4.12.1.tar.gz

Download URL	django_smart_ratelimit-4.12.1.tar.gz
Size	518.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`bf89f5b904efa00cf238592eb3e33a1d0a73d60b3e1b54458800a8da8a507c0d`
BLAKE2b-256 checksum How to use checksums	`fff817f498f178c27ef509e775daa9d286942c2ff836ea3eb0b4c14b873e8ea5`
Upload date	Jun 5, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.13`

Release files / django_smart_ratelimit-4.12.1-py3-none-any.whl

Download URL	django_smart_ratelimit-4.12.1-py3-none-any.whl
Size	229.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`9dcfee14ab32b002bfb0c22ada5c3aec8f7080d9b591759497e4654d1604dcdf`
BLAKE2b-256 checksum How to use checksums	`da8e23c9e568e4691ec68934acc586873a3e5dd3f92c07263fc635703a89649c`
Upload date	Jun 5, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.13`