Description
.. |ci| image:: https://github.com/alisaifee/flask-limiter/actions/workflows/main.yml/badge.svg?branch=master :target: https://github.com/alisaifee/flask-limiter/actions?query=branch%3Amaster+workflow%3ACI .. |codecov| image:: https://codecov.io/gh/alisaifee/flask-limiter/branch/master/graph/badge.svg :target: https://codecov.io/gh/alisaifee/flask-limiter .. |pypi| image:: https://img.shields.io/pypi/v/Flask-Limiter.svg?style=flat-square :target: https://pypi.python.org/pypi/Flask-Limiter .. |license| image:: https://img.shields.io/pypi/l/Flask-Limiter.svg?style=flat-square :target: https://pypi.python.org/pypi/Flask-Limiter .. |docs| image:: https://readthedocs.org/projects/flask-limiter/badge/?version=latest :target: https://flask-limiter.readthedocs.org/en/latest ************* Flask-Limiter ************* |docs| |ci| |codecov| |pypi| |license| **Flask-Limiter** adds rate limiting to `Flask <https://flask.palletsprojects.com>`_ applications. You can configure rate limits at different levels such as: - Application wide global limits per user - Default limits per route - By `Blueprints <https://flask-limiter.readthedocs.io/en/latest/recipes.html#rate-limiting-all-routes-in-a-blueprint>`_ - By `Class-based views <https://flask-limiter.readthedocs.io/en/latest/recipes.html#using-flask-pluggable-views>`_ - By `individual routes <https://flask-limiter.readthedocs.io/en/latest/index.html#decorators-to-declare-rate-limits>`_ **Flask-Limiter** can be `configured <https://flask-limiter.readthedocs.io/en/latest/configuration.html>`_ to fit your application in many ways, including: - Persistance to various commonly used `storage backends <https://flask-limiter.readthedocs.io/en/latest/#configuring-a-storage-backend>`_ (such as Redis, Memcached & MongoDB) via `limits <https://limits.readthedocs.io/en/stable/storage.html>`__ - Any rate limiting strategy supported by `limits <https://limits.readthedocs.io/en/stable/strategies.html>`__ Follow the quickstart below to get started or `read the documentation <http://flask-limiter.readthedocs.org/en/latest>`_ for more details. Quickstart =========== Install ------- .. code-block:: bash pip install Flask-Limiter Add the rate limiter to your flask app --------------------------------------- .. code-block:: python # app.py from flask import Flask from flask_limiter import Limiter from flask_limiter.util import get_remote_address app = Flask(__name__) limiter = Limiter( get_remote_address, app=app, default_limits=["2 per minute", "1 per second"], storage_uri="memory://", # Redis # storage_uri="redis://localhost:6379", # Redis cluster # storage_uri="redis+cluster://localhost:7000,localhost:7001,localhost:70002", # Memcached # storage_uri="memcached://localhost:11211", # Memcached Cluster # storage_uri="memcached://localhost:11211,localhost:11212,localhost:11213", # MongoDB # storage_uri="mongodb://localhost:27017", strategy="fixed-window", # or "moving-window", or "sliding-window-counter" ) @app.route("/slow") @limiter.limit("1 per day") def slow(): return "24" @app.route("/fast") def fast(): return "42" @app.route("/ping") @limiter.exempt def ping(): return 'PONG' Inspect the limits using the command line interface --------------------------------------------------- .. code-block:: bash pip install Flask-Limiter[cli] .. code-block:: bash $ FLASK_APP=app:app flask limiter limits app ├── fast: /fast │ ├── 2 per 1 minute │ └── 1 per 1 second ├── ping: /ping │ └── Exempt └── slow: /slow └── 1 per 1 day Run the app ----------- .. code-block:: bash $ FLASK_APP=app:app flask run Test it out ----------- The ``fast`` endpoint respects the default rate limit while the ``slow`` endpoint uses the decorated one. ``ping`` has no rate limit associated with it. .. code-block:: bash $ curl localhost:5000/fast 42 $ curl localhost:5000/fast 42 $ curl localhost:5000/fast <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> <title>429 Too Many Requests</title> <h1>Too Many Requests</h1> <p>2 per 1 minute</p> $ curl localhost:5000/slow 24 $ curl localhost:5000/slow <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> <title>429 Too Many Requests</title> <h1>Too Many Requests</h1> <p>1 per 1 day</p> $ curl localhost:5000/ping PONG $ curl localhost:5000/ping PONG $ curl localhost:5000/ping PONG $ curl localhost:5000/ping PONG
Release History
| Version | Changes | Urgency | Date |
|---|---|---|---|
| 4.1.1 | Imported from PyPI (4.1.1) | Low | 4/21/2026 |
| 4.1.0 | ## Deployment * Extract ``cli`` specific requirements to an extra ## Compatibility * Add python 3.14 support | Low | 12/3/2025 |
| 4.0.0 | ## Feature * Expose ``flask_limiter.Limit``, ``flask_limiter.RouteLimit``, ``flask_limiter.ApplicationLimit`` & ``flask_limiter.MetaLimit`` limit description classes that can be used to pass in default, application & meta limits to the ``Limiter`` extension. This allows for a more fine grained control for end users while also simplifying the internal implementation of different types of limits. ## Compatibility * Prefix all internal sub modules with underscore. All imports sh | Low | 9/30/2025 |
| 3.13 | > [!CAUTION] > This release has been yanked from pypi due to compatibility issues with Flask-AppBuilder & airflow. See #479 ## Feature * Expose ``flask_limiter.Limit``, ``flask_limiter.RouteLimit``, ``flask_limiter.ApplicationLimit`` & ``flask_limiter.MetaLimit`` limit description classes that can be used to pass in default, application & meta limits to the Limiter extension. This allows for a more fine grained control for end users while also simplifying the internal imp | Low | 9/12/2025 |
| 3.12 | ## Compatibility * Drop support for python 3.9 * Add install extra for valkey | Low | 3/15/2025 |
| 3.11.0 | ## Documentation * Improve documentation about rate limiting strategies ## Typing * Use builtin types (list, set, tuple) | Low | 3/11/2025 |
| 3.10.1 | ## Security * Change pypi release to use trusted publishing | Low | 1/16/2025 |
| 3.10.0 | ## Chores * Fix typing error with exempt decorator * Update types for window wrapper to use named tuple | Low | 1/5/2025 |
| 3.9.2 | ## Compatibility * Ensure wheels are uploaded to pypi as well (for real) | Low | 11/27/2024 |
| 3.9.0 | ## Chores * Update development dependencies ## Compatibility * Drop support for python 3.8 * Add support for python 3.13 * Add CI matrix entry for flask 3.1 | Low | 11/27/2024 |
| 3.8.0 | ## Bug fix * Ensure cost is accounted for when testing conditional limits | Low | 7/21/2024 |
| 3.7.0 | ## Bug fix * Fix errors with concurrent access to internal exemption maps during application startup. | Low | 5/19/2024 |
| 3.6.0 | ## Bug fix * Ensure `exempt` routes are exempt from meta limits as well | Low | 4/21/2024 |
| 3.5.1 | ## Chores * Update development dependencies * Use ruff for all linting * Update CI compatibility matrix | Low | 2/11/2024 |
| 3.5.0 | ## Feature * Add `meta_limits` to allow for creating upper limits for requesting clients to breach application rate limits. ## Bug fix * Ensure on breach callbacks can be configured using flask config | Low | 8/31/2023 |
| 3.4.1 | ## Bug fix - Ensure _version.py has stable content when generated using `git archive` from a tag regardless of when it is run. | Low | 8/26/2023 |
| 3.4.0 | ## Feature * Add extended configuration for application limits * `application_limits_exempt_when` * `application_limits_deduct_when` * `application_limits_per_method` ## Bug fix * Ensure blueprint static routes are exempt | Low | 8/22/2023 |
| 3.3.1 | ## Chores * Improve default limits documentation * Update documentation dependencies * Fix typing compatibility errors in headers | Low | 5/3/2023 |
| 3.3.0 | ## Bug Fix * Ensure per route limits are preferred (over application limits) when populating rate limiting headers in the case where no rate limit has been breached in the request. v3.3.0 ------ v3.3.0 ------ | Low | 2/27/2023 |
| 3.2.0 | ## Feature * Allow configuring request identity ## Chores * Improve linting with ruff * Update development dependencies v3.2.0 ------ v3.2.0 ------ | Low | 2/16/2023 |
| 3.1.0 | ## Feature * Skip logging an error if a decorated limit uses a callable to return the "current" rate limit and returns an empty string. Treat this is a signal that the rate limit should be skipped for this request. | Low | 12/29/2022 |
| 3.0.0 | ## Breaking changes * Change order of extension constructor arguments to only require ``key_func`` as the first positional argument and all other arguments as keyword arguments. * Separate positional/keyword arguments in limit/shared_limit decorators * Remove deprecated config variable RATELIMIT_STORAGE_URL * Remove legacy backward compatibility path for flask < 2 ## Features * Allow scoping regular limit decorators / context managers | Low | 12/28/2022 |
| 3.0.0b2 | ## Breaking changes * Remove deprecated config variable RATELIMIT_STORAGE_URL * Remove legacy backward compatibility path for flask < 2 * Enforce key_func as a required argument ## Chores * Simplify registration of decorated function & blueprint limits | Low | 12/28/2022 |
| 3.0.0b1 | ## Breaking changes * Change order of extension constructor arguments to only require ``key_func`` as the first positional argument and all other arguments as keyword arguments. * Separate positional/keyword arguments in limit/shared_limit decorators ## Features * Allow scoping regular limit decorators / context managers | Low | 12/27/2022 |
| 2.9.2 | ## Feature * Extend customization by http method to shared_limit decorator | Low | 12/26/2022 |
| 2.9.1 | ## Chores * Update documentation quick start * Refresh documentation for class based views | Low | 12/26/2022 |
| 2.9.0 | ## Features * Allow using `limit` & `shared_limit` decorators on pure functions that are not decorated as routes. The functions when called from within a request context will get rate limited. * Allow using `limit` as a context manager to rate limit a code block explicitly within a request ## Chores * Updated development dependencies * Fix error running tests depending on docker locally * Update internals to use dataclasses | Low | 12/24/2022 |
| 2.8.1 | ## Chores * Add sponsorship banner to rtd * Update documentation dependencies | Low | 11/15/2022 |
| 2.8.0 | ## Breaking changes * Any exception raised when calling an ``on_breach`` callback will be re-raised instead of being absorbed unless ``swallow_errors`` is set. In the case of ``swallow_errors`` the exception will now be logged at ``ERROR`` level instead of ``WARN`` * Reduce log level of rate limit exceeded log messages to ``INFO`` | Low | 11/13/2022 |
| 2.7.0 | ## Bug Fix * Add default value for RateLimitExceeded optional parameter * Fix suppression of errors when using conditional deduction ([Issue 363](https://github.com/alisaifee/flask-limiter/issues/363)) | Low | 10/25/2022 |
| 2.6.3 | ## Compatibility * Ensure typing_extensions dependency has a minimum version ## Chores * Documentation tweaks * Update CI to use 3.11 rc2 | Low | 9/22/2022 |
| 2.6.2 | ## Chores * Improve quick start documentation | Low | 8/24/2022 |
| 2.6.1 | ## Usability * Emit warning when in memory storage is used as a default when no storage uri is provided | Low | 8/24/2022 |
| 2.6.0 | ## Feature * Expand use of ``on_breach`` callback to return a ``Response`` object that will be used as the error response on rate limits being exceeded | Low | 8/11/2022 |
| 2.5.1 | ## Compatibility * Migrate use of `flask._request_ctx_stack` to `flask.globals.request_ctx` to support Flask 2.2+ ## Chores * Expand CI matrix to test against Flask 2.0,2.1 & 2.2 * Make tests compatible with Flask 2.2.+ | Low | 8/6/2022 |
| 2.5.0 | ## Features * Ensure multiple extension instances registered on a single application exercise before/after request hooks ## Chores * Improve documentation | Low | 7/8/2022 |
| 2.4.6 | ## Chore * Add python 3.11 to CI matrix | Low | 6/7/2022 |
| 2.4.5.1 | ## Chore * Automate github releases | Low | 4/22/2022 |
| 2.4.5 | Release 2.4.5 | Low | 4/22/2022 |
| 2.4.0 | ## Feature * Add CLI for inspecting & clearing rate limits ## Bug Fix * Ensure exempt decorator can be used with flags for view functions ## Chores * Refactor rate limit resolution to limit manager | Low | 4/22/2022 |
| 2.3.3 | ## Bug Fix * Ensure `request.blueprint` is actually registered on the current app before using it for blueprint limits or exemptions. ([Issue 336](https://github.com/alisaifee/flask-limiter/issues/336)) | Low | 4/22/2022 |
| 2.3.2 | ## Feature * Extend cost parameter to default & application limits ## Chore * Improve type strictness / checking * Improve documentation on landing page | Low | 4/22/2022 |
| 2.3.1 | ## Bug Fixes * Add missing extras requirements for installation * Add py.typed for PEP 561 compliance | Low | 4/22/2022 |
| 2.3.0 | ## Features * Expose option to register a callback for rate limit breaches of default limits via the `~flask_limiter.Limiter.on_breach` constructor parameter * Replace use of `flask.g` with request context for keeping track of extension state (`327`) * Rework implementation of `~flask_limiter.Limiter.exempt` to accomodate nested blueprints. (`326`) ## Chores * Add python 3.11 to CI * Extract management and filtering of limits to LimitManager * Improve correctness of resolving inher | Low | 4/22/2022 |
| 2.2.0 | ## Feature * Allow a function to be used for the ``cost`` parameter to limiter decorators. | Low | 4/22/2022 |
| 2.1.1 | ## Chore * Update documentation theme | Low | 4/22/2022 |
| 2.1 | ## Feature * Add ``current_limit`` attribute to extension to allow clients to fetch the relevant current limit that was evaluated. * Update extension constructor parameters to match flask config for header control * Add ``on_breach`` callback for ``limit`` and ``shared_limit`` decorators to be used as hooks for when a limit is breached * Add ``cost`` argument to ``limit`` and ``shared_limit`` to control how much is deducted when a hit occurs. ## Chore * Improve documentation arou | Low | 4/22/2022 |
| 2.0.4 | ## Chore * Documentation theme upgrades * Integrate pytest-docker plugin * Mass linting ## Deprecation * Removed deprecated RATELIMIT_GLOBAL config * Added deprecation doc for RATELIMIT_STORAGE_URL config | Low | 4/22/2022 |
| 2.0.3 | Documentation & test tweaks | Low | 4/22/2022 |
| 2.0.2 | ## Features * Pin Flask, limits to >= 2 * Add type hints | Low | 4/22/2022 |