Install & Compatibility
Where this runs
tested against v0.2.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 36.9MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 4.2s · import 0.000s · 36MB
35MB installed
● package 35MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
FastAPILimiter
✓ from fastapi_limiter import FastAPILimiter
RateLimiter
✓ from fastapi_limiter.depends import RateLimiter
Redis
✓ from redis.asyncio import Redis
✗ from redis import Redis
For asynchronous FastAPI applications, ensure you import the asyncio-compatible Redis client (`redis.asyncio.Redis`) to prevent blocking the event loop. The synchronous client is only appropriate for blocking contexts.
This quickstart demonstrates how to initialize `fastapi-limiter` with an async Redis client during FastAPI's application startup event. It then applies different rate limits to two distinct endpoints using the `RateLimiter` dependency. The Redis connection uses an environment variable for configuration.
import os
from fastapi import FastAPI, Depends
from fastapi_limiter import FastAPILimiter
from fastapi_limiter.depends import RateLimiter
from redis.asyncio import Redis # Use asyncio for FastAPI
app = FastAPI()
# Configure Redis URL via environment variable or default to localhost
REDIS_URL = os.environ.get('REDIS_URL', 'redis://localhost:6379')
@app.on_event('startup')
async def startup():
redis_client = Redis.from_url(REDIS_URL, encoding='utf8', decode_responses=True)
await FastAPILimiter.init(redis_client)
print("FastAPILimiter initialized.")
@app.get('/', dependencies=[Depends(RateLimiter(times=2, seconds=5))])
async def homepage():
return {'message': 'Hello world!'}
@app.get('/limited', dependencies=[Depends(RateLimiter(times=1, seconds=10))])
async def limited_endpoint():
return {'message': 'This endpoint is more limited!'}
# To run this example:
# 1. Install uvicorn: pip install uvicorn
# 2. Run Redis locally (e.g., via Docker: docker run --name some-redis -p 6379:6379 -d redis)
# 3. Save the code as main.py
# 4. Execute: uvicorn main:app --reload
Debug
Known issues
gotchaYou must explicitly call `await FastAPILimiter.init(redis_client)` during your FastAPI application's startup event (e.g., in `@app.on_event('startup')`). Failing to do so will result in the rate limiter not being initialized and will cause errors when endpoints attempt to use it.fixEnsure `FastAPILimiter.init` is properly awaited within an asynchronous startup function linked to `@app.on_event('startup')`. affects: >=0.1.0
gotchaFor async FastAPI applications, always use `redis.asyncio.Redis` (or methods like `Redis.from_url` from `redis.asyncio`) for your Redis client. Using the synchronous `redis.Redis` directly in an `async def` context will block the event loop, leading to performance degradation and concurrency issues.fixImport `Redis` from `redis.asyncio` and ensure all Redis client operations are `await`ed.
affects: >=0.1.0
breakingAs a 0.x.x version library, `fastapi-limiter` may introduce breaking changes in minor or patch releases without strictly adhering to semantic versioning. The API surface may evolve rapidly.fixIt is highly advisable to pin your dependency to an exact version (e.g., `fastapi-limiter==0.2.0`) and carefully review changelogs or GitHub releases before upgrading.
affects: All 0.x.x versions
gotchaThe `redis` library, which provides the Redis client, is a peer dependency and not automatically installed alongside `fastapi-limiter`. You must install it separately for the library to function.fixEnsure you include `redis` in your project's dependencies and install it (e.g., `pip install redis`).
affects: >=0.1.0
Upgrade
Version history
0.2.0latest on PyPI · released Feb 6, 2026
Audit
Dependencies
redisrequiredThe `redis` library (specifically `redis>=4.0` for asyncio support) is required to provide the Redis client functionality, which serves as the backend for all rate limiting operations.