---
id: token-throttler
version: "1.5.1"
license: MIT
license_treatment: permissive
maintenance: dormant
---

# token-throttler — Token throttler is an extendable rate-limiting library somewhat based on a token bucket algorithm

License: permissive · Maintenance: dormant · Downloads: 148.7K/mo

## What it is and what it does

Token throttler is a rate-limiting library that enforces request quotas using a token bucket algorithm. It allows you to define buckets with a maximum token count and replenishment time, then consume tokens before allowing actions to proceed. The library supports both blocking (synchronous) and non-blocking (asynchronous) modes, and can be used either manually by calling consume() or via decorators applied to functions and FastAPI routes.

The package is designed to be extensible: it ships with in-memory (RuntimeStorage) and Redis storage backends, and you can implement custom storage by extending the base storage classes. Configuration can be set globally or per-instance, with options to enable thread locking for race-condition safety and fail-safe behavior for missing identifiers. It officially supports Python 3.8 and later.

Use it for:

- Protect API endpoints from abuse by limiting requests per user or IP address using FastAPI middleware
- Rate-limit background job processing by throttling function calls across multiple workers with Redis storage
- Enforce quota limits on internal service calls to prevent cascading failures or resource exhaustion
- Implement sliding-window rate limits on database queries or external API calls within a single application
- Decorate expensive functions to prevent them from being called more than N times per time window

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Token throttler implements rate limiting using a token bucket algorithm, supporting both synchronous and asynchronous code with pluggable storage backends and decorator-based or manual usage patterns.

Yes, if you need straightforward token-bucket rate limiting and can accept the project's dormant maintenance status. The library is simple to integrate, has no runtime dependencies, and works with modern Python versions. However, if you require active maintenance, frequent updates, or are building mission-critical systems, consider whether the 860-day gap since the last release poses a risk for your use case.

## Install

pip install token-throttler
uv add token-throttler
poetry add token-throttler

## Installing token-throttler

Before you install: Low install friction with no runtime dependencies. Marked dormant (860 days since last release), though classifiers indicate Production/Stable status and support for Python 3.8 through 3.12.

License in practice: MIT license (permissive) places no restrictions on use, modification, or distribution in proprietary or open-source projects.

Quickstart:

from token_throttler import TokenThrottler, TokenBucket
from token_throttler.storage import RuntimeStorage

throttler = TokenThrottler(1, RuntimeStorage())
throttler.add_bucket("endpoint", TokenBucket(10, 10))
if throttler.consume("endpoint"):
    print("Request allowed")
else:
    print(f"Retry in {throttler.wait_time('endpoint')} seconds")

Verify before relying:

- Whether dormant status (no recent commits visible) affects reliability for new deployments or bug fixes
- Performance characteristics under high concurrency or with large numbers of buckets
- Whether Redis storage extra is actively maintained given the project's maintenance status

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: dormant
- Downloads: 148.7K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

rate limiting library, token bucket algorithm, request throttling, api rate limiter, async rate limiting, fastapi throttling, token bucket implementation, rate-limiting, token-bucket, async-support

[View on SkillFed](https://skillfed.io/packages/token-throttler) · [View on PyPI](https://pypi.org/project/token-throttler/)