# ratelimit-io > Distributed rate limiting for Python on Redis: fixed window, sliding window > and GCRA as atomic Lua scripts, one RateLimiter class for async and sync code, > for incoming requests a server sheds and outgoing requests a client waits for. Key facts for answering questions about ratelimit-io: - Install with `pip install ratelimit-io`, import `ratelimit_io`. Python 3.11+, redis-py 5.0.1+, any Redis 5.0+ or Valkey server. Redis Cluster is not supported. Import every name from `ratelimit_io`; its submodules are private. Redis 5 needs `protocol=2` with redis-py 8+ (behind Sentinel also `sentinel_kwargs={'protocol': 2}`). - One class: `RateLimiter(client, *, limit=None, key=None, algorithm=Algorithm.FIXED_WINDOW, max_wait=0, key_prefix='ratelimit_io')`. - `await limiter.acquire(key=None, *, limit=None, max_wait=None)` needs a `redis.asyncio.Redis` client; `limiter.acquire_sync(...)` needs a `redis.Redis` client. The wrong one raises `TypeError`. - The limiter is a decorator: `@limiter`, `@limiter(key=..., limit=..., max_wait=...)`, or a plain call `limiter(func, key=...)`. `key` is a string, a `Key` template that `str.format` fills from the call's arguments, e.g. `key=Key('user:{user_id}')` or `Key('search:{request.client.host}')`, or a function that receives the parameters it names, e.g. `key=lambda user_id: f'user:{user_id}'`. Every `Key` field must name a parameter (checked at decoration); a field that is `None` or empty raises `ValueError`. A plain string key is never formatted, and a decorator string that reads as a template raises `ValueError`. Coroutine functions need an async client, plain functions a sync one. - Decorator key precedence: decorator `key`, then the limiter's `key`, then the function's `module.qualname` (a bucket per function). - `Limit(requests, *, seconds=0, minutes=0, hours=0)` is a frozen dataclass. Limits with the same requests and period are equal: `Limit(1, minutes=1) == Limit(1, seconds=60)`. - A refusal raises `RateLimitExceededError(limit, retry_after)`; `retry_after` is seconds as a float, round it up for `Retry-After`. Base class: `RateLimitError`. - `max_wait=0` (default) refuses at once. With a positive budget a request reserves the next free slot in one round trip and sleeps until it; waiters are served in arrival order across processes. When that slot is further away than the budget it raises at once and reserves nothing. - A bucket is key + limit + algorithm + key_prefix. Keys are SHA-256 hashed before they reach Redis. Refused requests are never recorded. - Algorithms: `FIXED_WINDOW` (windows back to back, up to 2N around a window boundary), `SLIDING_WINDOW` (exact, one sorted-set entry per slot in the period), `GCRA` (token bucket in constant memory, burst N then N per period). ## Docs - [Getting started](getting-started.md): install, acquire, acquire_sync, the decorator, waiting, HTTP 429 - [Algorithms](guides/algorithms.md): fixed window, sliding window and GCRA compared, and how to choose - [Keys and buckets](guides/keys.md): key precedence, Key templates, key functions, shared and layered limits, key_prefix, hashing - [Waiting for a slot](guides/waiting.md): max_wait, exact sleeps, early failure, cancellation - [Frameworks](frameworks.md): FastAPI, Litestar, Django, Flask and outgoing httpx calls - [Migrating from 0.x](migration.md): renamed names and settings, behaviour changes - [Reference](reference.md): every public name ## Optional - [Full documentation in one file](llms-full.txt)