This release is a pre-release and may not be stable for production use.
fastapi-cache-stable
Community-maintained stable fork of fastapi-cache2. The latest published release is beta
0.3.0b1, based onv0.2.2; this branch prepares an unpublished0.3.0rc1. Neither is recommended for production before the release gates pass. Thefastapi_cacheimport and documented core API signatures are preserved; intentional behavior changes are described in MIGRATION.md. See COMPATIBILITY.md, MIGRATION.md, SUPPORT.md, SECURITY.md and FORK_ORIGIN.md. Not affiliated with the original author. The upcoming stable0.3.0release will install on Python>=3.8,<3.14. Python 3.8–3.10 remain legacy functional-compatibility targets only; security support is limited to server-side CPython 3.11–3.13. Pyodide/browser/Node runtimes are not tested or covered by these guarantees; this does not claim functional incompatibility. Python 3.14 remains untested and outside this release's metadata range. The already-published0.3.0b1artifact and its metadata remain unchanged.
Implemented in this beta: error responses are not cached, opt-in
TypedJsonCoderfor Pydantic v2, theclear()fixes, the auth/privacy bypass, the InMemoryexpire=None/instance-isolation fixes, theCache-Controlfix, the stable ETag, the_spec_typenamespacing, the non-JSON response bypass, and an explicit secondFastAPICache.init()call that raises unless you passforce=True. Memcached and DynamoDB remain experimental. For the target stable0.3.0, DynamoDB is supported only on Python>=3.10; the already-published0.3.0b1artifact and metadata are unchanged. See MIGRATION.md.
Branch model:
stableis the only maintained and release branch.mainmirrors the upstream project and is not a second development branch.
Introduction
fastapi-cache is a tool to cache FastAPI endpoint and function results, with
backends supporting Redis, Memcached, and Amazon DynamoDB.
Features
- Supports
redis,memcache,dynamodb, andin-memorybackends. - Easy integration with FastAPI.
- Inherited
ETagandCache-Controlsupport, including conditionalIf-None-Matchrequests.Cache-Controlemits only validmax-agevalues, and ETags are stable, quoted weak validators.
Beta caveat:
0.3.0b1includes the auth/privacy bypass, the InMemoryexpire=None/instance-isolation fixes, theCache-Controlfix, the stable ETag, the_spec_typenamespacing, the non-JSON response bypass, and explicit re-configuration throughFastAPICache.reset()orforce=True. Memcached and DynamoDB remain experimental. See COMPATIBILITY.md.
Requirements
- FastAPI
rediswhen usingRedisBackend.memcachewhen usingMemcacheBackend.- For target stable
0.3.0,aiobotocoreandaiohttp>=3.14.4when usingDynamoBackendon Python>=3.10. - The target stable
0.3.0does not install DynamoDB client dependencies on Python 3.8/3.9; Redis and InMemory remain the legacy backend options. The published0.3.0b1metadata is unchanged and is not recommended for production.
Install
0.3.0b1 is the latest published beta referenced here. The repository prepares an
unpublished 0.3.0rc1; do not assume it is available on TestPyPI/PyPI yet.
These commands install the published beta:
> pip install "fastapi-cache-stable==0.3.0b1"
or
> pip install "fastapi-cache-stable[redis]==0.3.0b1"
or
> pip install "fastapi-cache-stable[memcache]==0.3.0b1"
or
> pip install "fastapi-cache-stable[dynamodb]==0.3.0b1"
Migrating from fastapi-cache2
The intended low-friction upgrade is fastapi-cache2==0.2.2 →
fastapi-cache-stable, keeping your existing from fastapi_cache ...
imports and usual @cache(...) calls. For GET/JSON with standalone Redis
or InMemory, the default key algorithm is unchanged. Uninstall the old
distribution first: the two packages install the same Python module and
must not coexist. Update the dependency in your application's lockfile.
This is not a promise of identical behavior in every case: authenticated
requests bypass cache by default, second init() calls now raise, and
clear(key=...) is intentionally narrower. Old private/special Redis
entries may require targeted invalidation. See the
quick migration checklist,
verification scenarios and rollback instructions.
Usage
Quick Start
Redis 7 / redis-py 4.x example. Initialize once per application lifespan,
then close owned resources and reset the process-global cache configuration
on teardown. Avoid routine use of force=True.
from contextlib import asynccontextmanager
from typing import AsyncIterator
from fastapi import FastAPI
from redis import asyncio as aioredis
from fastapi_cache import FastAPICache
from fastapi_cache.backends.redis import RedisBackend
from fastapi_cache.decorator import cache
@asynccontextmanager
async def lifespan(_: FastAPI) -> AsyncIterator[None]:
redis_client = aioredis.from_url(
"redis://localhost:6379/0", decode_responses=False
)
FastAPICache.init(RedisBackend(redis_client), prefix="fastapi-cache")
try:
yield
finally:
FastAPICache.reset()
await redis_client.close() # redis-py 4.x
app = FastAPI(lifespan=lifespan)
@app.get("/")
@cache(expire=60)
async def index():
return {"hello": "world"}
For a process-local test fixture, use
FastAPICache.init(InMemoryBackend(), prefix="fastapi-cache")
after importing InMemoryBackend from
fastapi_cache.backends.inmemory. InMemory data is not shared across workers.
Initialization
Call FastAPICache.init() once per process at application startup. A
second call raises RuntimeError; test fixtures that re-enter a lifespan
must close owned backend resources and call FastAPICache.reset() during
teardown. force=True permits deliberate replacement but does not
close the old connection pool or isolate multiple FastAPI apps in one process.
Use the @cache decorator
If you want cache a FastAPI response transparently, you can use the @cache
decorator between the router decorator and the view function.
| Parameter | type | default | description |
|---|---|---|---|
expire |
int |
sets the caching time in seconds | |
namespace |
str |
"" |
namespace to use to store certain cache items |
coder |
Coder |
JsonCoder |
which coder to use, e.g. JsonCoder |
key_builder |
KeyBuilder callable |
default_key_builder |
which key builder to use |
injected_dependency_namespace |
str |
__fastapi_cache |
prefix for injected dependency keywords. |
cache_authenticated |
bool |
None |
per-endpoint override for caching authenticated requests; global default is False; requires an identity-aware key_builder. |
The cache_status_header argument belongs to FastAPICache.init(), not
@cache(). It controls the HIT / MISS response header.
You can also use the @cache decorator on regular functions to cache their result.
Injected Request and Response dependencies
The cache decorator injects dependencies for the Request and Response
objects, so that it can add cache control headers to the outgoing response, and
return a 304 Not Modified response when the incoming request has a matching
If-None-Match header. The ETag is a quoted weak validator derived from a stable SHA-256
digest of the cached representation; If-None-Match supports weak comparison,
comma-separated lists and *. Conditional requests are evaluated on both hits and misses,
and malformed entity-tags are ignored. This only happens if the decorated endpoint doesn't
already list these dependencies already.
The keyword arguments for these extra dependencies are named
__fastapi_cache_request and __fastapi_cache_response to minimize collisions.
Use the injected_dependency_namespace argument to @cache to change the
prefix used if those names would clash anyway.
Supported data types
The default JsonCoder stores any data type that FastAPI can convert to JSON, including
Pydantic models and dataclasses. On a cache hit it returns the decoded JSON value (plain
dicts/lists), not the annotated model; this is the legacy fastapi-cache2 behavior.
Pydantic v2 users can opt into typed restoration with TypedJsonCoder:
from fastapi_cache import FastAPICache
from fastapi_cache.coder import TypedJsonCoder
FastAPICache.init(backend, coder=TypedJsonCoder)
or per endpoint:
from .models import SomeModel, create_some_model
@app.get("/foo")
@cache(expire=60, coder=TypedJsonCoder)
async def foo() -> SomeModel:
return create_some_model()
TypedJsonCoder uses the endpoint return annotation to restore the annotated type and
propagates validation errors. It requires Pydantic v2; Pydantic v1 and annotations that
cannot be represented by a Pydantic v2 schema keep the legacy decoded behavior.
For broader type support, use fastapi_cache.coder.PickleCoder or implement a custom coder
(see below).
PickleCoder deserializes with Python's pickle and must only be used with a cache backend
whose contents are trusted and integrity-protected. An attacker who can alter cached bytes
may be able to execute code when those values are read. JsonCoder is the default.
Response handling
JsonCoder caches only simple JSONResponse objects: status 200, media type
application/json, no custom headers, and no background task. Other Response subclasses
are returned directly and are not cached: StreamingResponse, FileResponse,
RedirectResponse, plain Response, template responses, and JSONResponse objects with
metadata that would be lost on a cache hit. Custom coders can override
Coder.can_encode() to opt in; PickleCoder caches response objects it can reproduce
faithfully (JSONResponse, plain Response, RedirectResponse) and bypasses streaming,
file, and template responses. Responses with Set-Cookie, Cache-Control: no-store or
Cache-Control: private, or a background task are never cached, regardless of the coder.
If the endpoint or a dependency sets Set-Cookie, Cache-Control: no-store/private, a
background task, a non-200 status, or any header other than the automatic content-length
on the injected response object, the call is not cached. This covers dict/list returns whose
final HTTP metadata comes from that object.
User payloads that contain _spec_type are preserved as normal data; the internal marker is
namespaced as __fastapi_cache_spec_type__.
Custom coder
By default use JsonCoder, you can write custom coder to encode and decode cache result, just need
inherit fastapi_cache.coder.Coder.
from typing import Any
import orjson
from fastapi.encoders import jsonable_encoder
from fastapi_cache import Coder
class ORJsonCoder(Coder):
@classmethod
def encode(cls, value: Any) -> bytes:
return orjson.dumps(
value,
default=jsonable_encoder,
option=orjson.OPT_NON_STR_KEYS | orjson.OPT_SERIALIZE_NUMPY,
)
@classmethod
def decode(cls, value: bytes) -> Any:
return orjson.loads(value)
@app.get("/")
@cache(expire=60, coder=ORJsonCoder)
async def index():
return dict(hello="world")
Custom key builder
By default the default_key_builder builtin key builder is used; this creates a
cache key from the function module and name, and the positional and keyword
arguments converted to their repr() representations, encoded as a MD5 hash.
You can provide your own by passing a key builder in to @cache(), or to
FastAPICache.init() to apply globally.
For example, if you wanted to use the request method, URL and query string as a cache key instead of the function identifier you could use:
from starlette.requests import Request
from starlette.responses import Response
def request_key_builder(
func,
namespace: str = "",
*,
request: Request = None,
response: Response = None,
args=(),
kwargs=None,
):
if request is None:
raise ValueError("This builder requires an HTTP Request")
return ":".join([
namespace,
request.method.lower(),
request.url.path,
repr(sorted(request.query_params.items()))
])
@app.get("/")
@cache(expire=60, key_builder=request_key_builder)
async def index():
return dict(hello="world")
This request-URL builder is appropriate for public data only. A custom
builder must include every value that affects the response, particularly
validated identity, tenant and permissions when authenticated caching is
explicitly enabled. DB session objects with changing repr() values can
otherwise produce perpetual misses; see the migration checklist.
Authenticated requests
By default, requests with a non-empty Authorization or Cookie header bypass the cache:
the endpoint runs normally and nothing is read from or written to the backend. Public
requests keep caching.
This is a conservative default. Session cookies are covered because they use the Cookie
header. Empty headers are treated as unauthenticated. Functions decorated without a
Request parameter have no HTTP identity context and keep using the cache.
To cache authenticated responses, opt in explicitly and provide a key builder that includes the identity:
import hashlib
import hmac
import os
from starlette.requests import Request
from fastapi_cache import FastAPICache
from fastapi_cache.decorator import cache
CACHE_KEY_SECRET = os.environ["CACHE_KEY_SECRET"].encode()
def identity_key_builder(
func,
namespace: str = "",
*,
request: Request = None,
response=None,
args,
kwargs,
):
identity = ""
if request is not None:
identity = "|".join(
[
request.headers.get("Authorization", ""),
request.headers.get("Cookie", ""),
request.headers.get("X-Tenant-Id", ""),
]
)
key_material = f"{identity}|{args}|{kwargs}"
digest = hmac.new(
CACHE_KEY_SECRET,
key_material.encode(),
hashlib.sha256,
).hexdigest()
return f"{namespace}:{func.__module__}:{func.__name__}:{digest}"
FastAPICache.init(backend, cache_authenticated=True, key_builder=identity_key_builder)
@app.get("/me")
@cache(expire=60)
async def me(request: Request):
...
The key builder must include every dimension that affects the response: token, session, tenant, permissions, and any other validated principal state. Prefer the principal your app already validated over raw headers. Do not put credentials in plaintext in keys or logs; use HMAC-SHA256 with an application secret.
If cache_authenticated=True is used with the default key builder, an authenticated request
raises ValueError before the cache is accessed. The flag can also be set per endpoint:
@cache(cache_authenticated=True, key_builder=identity_key_builder).
The automatic bypass only detects Authorization and Cookie. If your app uses X-API-Key,
proxy-injected headers, request.state, or internal dependencies, review your cache strategy.
cache_authenticated=True does not make an unsafe key builder safe.
This protects the application cache. It does not configure CDN, reverse-proxy, or browser caching.
Upgrading from 0.3.0a1 or earlier: old entries written for authenticated requests may
remain under the default key. Clear or rotate the cache namespace before deploying, including
all instances/workers and persistent Redis caches. The bypass is not retroactive.
Backend notes
InMemoryBackend
The InMemoryBackend stores cache data in memory and only deletes when an
expired key is accessed. This means that if you don't access a function after
data has been cached, the data will not be removed automatically.
expire=None means no expiration. Each backend instance owns its store and lock, so a new
instance does not see entries from another instance. Do not share one instance across event
loops or threads; use one instance per loop/thread. Subclasses that override __init__()
must call super().__init__(). InMemory is process-local; use Redis or Memcached for
cross-process sharing. expire=0 keeps the legacy fallback to the global expire value.
get_with_ttl returns -1 for no-expiration entries; the decorator omits max-age for
those entries and for expire=None.
RedisBackend
When using the Redis backend, please make sure you pass in a redis client that does not decode responses (decode_responses must be False, which is the default). Cached data is stored as bytes (binary), decoding these in the Redis client would break caching.
RedisBackend is tested with Redis 7 and redis-py 4.6.0. The redis extra pins
redis = "^4.2.0rc1", which does not include redis-py 5/6; those clients are untested.
Broader Redis client/server support is targeted for a later release.
Tests and coverage
coverage run -m pytest
coverage html
xdg-open htmlcov/index.html
License
This project is licensed under the Apache-2.0 License.
Metadata
Release files for fastapi-cache-stable 0.3.0rc1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| fastapi_cache_stable-0.3.0rc1.tar.gz | 50.6 kB | With provenance | Details for fastapi_cache_stable-0.3.0rc1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| fastapi_cache_stable-0.3.0rc1-py3-none-any.whl | Python 3 | none | any | Details for fastapi_cache_stable-0.3.0rc1-py3-none-any.whl |
Total release size: 76.6 kB
Release files / fastapi_cache_stable-0.3.0rc1.tar.gz
| Download URL | fastapi_cache_stable-0.3.0rc1.tar.gz |
|---|---|
| Size | 50.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
374cac1c57948f2fc63613b744c2609a788177edf0988261d518019eea173415
|
|
BLAKE2b-256 checksum How to use checksums |
c5fb549a02890aada2688b0d7ff6d11b57b6718d6f17de1d7caa9247b5215cfe
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logRelease files / fastapi_cache_stable-0.3.0rc1-py3-none-any.whl
| Download URL | fastapi_cache_stable-0.3.0rc1-py3-none-any.whl |
|---|---|
| Size | 26.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
251d5249feb319e99ba3438c929b618124a34525a4188dbe3817973d1edba6db
|
|
BLAKE2b-256 checksum How to use checksums |
78ad91e1527a19ec84834f9c38eb6cd8be96edb780d736c3b8cfb2c96149a0f2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logSecurity for fastapi-cache-stable 0.3.0rc1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for fastapi_cache_stable-0.3.0rc1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.