Install & Compatibility
Where this runs
tested against v3.4.1 · 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.915 runs
installs and imports cleanly · install 0.0s · import 0.378s · 22.4MB
glibcpy 3.10–3.915 runs
installs and imports cleanly · install 1.7s · import 0.337s · 23MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Throttled
✓ from throttled import Throttled
Use for synchronous applications.
RateLimiterType
✓ from throttled import RateLimiterType
Enum for specifying rate limiting algorithms.
Throttled (async)
✓ from throttled.asyncio import Throttled
✗ from throttled import Throttled
For asynchronous (async/await) applications, explicitly import from `throttled.asyncio`. Using the sync import in an async context will lead to errors.
RedisStore
✓ from throttled.store import RedisStore
Used for configuring a Redis storage backend.
This quickstart demonstrates both synchronous and asynchronous usage of `throttled-py` as a decorator. It uses the `TOKEN_BUCKET` algorithm for the synchronous example and `SLIDING_WINDOW` for the asynchronous one, with an optional Redis backend configured via `REDIS_URL` for distributed rate limiting. Ensure `throttled-py[redis]` is installed and a Redis instance is accessible for distributed storage.
import os
import time
from throttled import Throttled, RateLimiterType
# Configure Redis connection via URL for example, falling back to localhost
REDIS_URL = os.environ.get('REDIS_URL', 'redis://localhost:6379/0')
# Example with RedisStore
# Note: Requires 'throttled-py[redis]' to be installed.
# If Redis is not available, this example will use In-MemoryStore as a fallback implicitly
# or explicitly set store=MemoryStore() for local testing without redis.
# Create a throttler instance with Token Bucket algorithm, 1 request per second, burst 1.
# Key is dynamically generated from the function name.
@Throttled(using=RateLimiterType.TOKEN_BUCKET.value, quota="1/s burst 1", store_url=REDIS_URL)
def process_request(request_id):
print(f"Processing request {request_id} at {time.time()}")
return f"Processed {request_id}"
print("Starting throttled requests...")
for i in range(5):
try:
result = process_request(i)
print(f"Success: {result}")
except Exception as e:
print(f"Failed to process request {i}: {e}")
time.sleep(0.5) # Simulate some interval between calls
print("\nTrying with async Throttled (requires `throttled-py[redis]` and a running Redis for distributed behavior):")
import asyncio
from throttled.asyncio import Throttled as AsyncThrottled
from throttled.asyncio import RateLimiterType as AsyncRateLimiterType
@AsyncThrottled(using=AsyncRateLimiterType.SLIDING_WINDOW.value, quota="2/m", store_url=REDIS_URL)
async def async_process_request(request_id):
print(f"Async processing request {request_id} at {time.time()}")
await asyncio.sleep(0.1) # Simulate async work
return f"Async processed {request_id}"
async def main():
for i in range(5):
try:
result = await async_process_request(i)
print(f"Async Success: {result}")
except Exception as e:
print(f"Async Failed to process request {i}: {e}")
await asyncio.sleep(1) # Simulate some interval
if __name__ == '__main__':
# Note: If redis-py is not installed or Redis is not running,
# the store_url might implicitly fallback to in-memory behavior
# or raise connection errors. Ensure Redis is accessible for full distributed functionality.
try:
asyncio.run(main())
except ImportError:
print("\nSkipping async example: throttled-py[redis] might not be installed or redis-py is missing.")
except Exception as e:
print(f"\nError during async execution: {e}")
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'throttled'
This error occurs when the 'throttled' package is not installed in the Python environment.
fixInstall the package using pip: 'pip install throttled-py'.
ImportError: cannot import name 'Throttled' from 'throttled'
This error occurs when the 'throttled' package is installed but the import statement is incorrect.
fixEnsure the import statement is correct: 'from throttled import Throttled'.
AttributeError: module 'throttled' has no attribute 'Throttled'
This error occurs when the 'throttled' package is installed but the import statement is incorrect.
fixEnsure the import statement is correct: 'from throttled import Throttled'.
TypeError: Throttled() missing 1 required positional argument: 'key'
This error occurs when instantiating the 'Throttled' class without providing the required 'key' argument.
fixProvide the 'key' argument when creating an instance: 'throttle = Throttled(key="/api/v1/resource")'.
LimitedError: Rate limit exceeded: remaining=0, reset_after=60, retry_after=60
This error occurs when the rate limit has been exceeded for a given key.
fixAdjust the rate limit settings or implement a retry mechanism after the specified 'retry_after' duration.
Upgrade
Version history
3.4.1latest on PyPI · released Aug 1, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.10 or newer since v3.0.0.
redisoptionalRequired for Redis-based storage backends for distributed rate limiting. Installed via the `[redis]` extra.