django-smart-ratelimit 4.0.0

A flexible and efficient rate limiting library for Django applications

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, 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, and custom load indicators

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
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
Django	3.2, 4.0, 4.1, 4.2, 5.0, 5.1

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

Sponsors

Support the ongoing development of Django Smart Ratelimit:

License

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