Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

fastapi-cache-stable

Community-maintained stable fork of fastapi-cache2. This is a beta (0.3.0b1) based on v0.2.2. It is experimental and still not recommended for production. The fastapi_cache import and public API are unchanged. See COMPATIBILITY.md, MIGRATION.md, SUPPORT.md, SECURITY.md and FORK_ORIGIN.md. Not affiliated with the original author.

Implemented in this beta: error responses are not cached, opt-in TypedJsonCoder for Pydantic v2, the clear() fixes, the auth/privacy bypass, the InMemory expire=None/instance-isolation fixes, the Cache-Control fix, the stable ETag, the _spec_type namespacing, the non-JSON response bypass, and an explicit second FastAPICache.init() call that raises unless you pass force=True. See MIGRATION.md.

Branch model: stable is the only maintained and release branch. main mirrors the upstream project and is not a second development branch.

pypi license CI

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, and in-memory backends.
  • Easy integration with FastAPI.
  • Inherited ETag and Cache-Control support, including conditional If-None-Match requests. Cache-Control emits only valid max-age values, and ETags are stable, quoted weak validators.

Beta caveat: 0.3.0b1 includes the auth/privacy bypass, the InMemory expire=None/instance-isolation fixes, the Cache-Control fix, the stable ETag, the _spec_type namespacing, the non-JSON response bypass, and explicit re-configuration through FastAPICache.reset() or force=True. Memcached and DynamoDB remain experimental. See COMPATIBILITY.md.

Requirements

  • FastAPI
  • redis when using RedisBackend.
  • memcache when using MemcacheBackend.
  • aiobotocore when using DynamoBackend.

Install

0.3.0b1 is a pre-release. Install the exact version:

> 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"

Usage

Quick Start

from collections.abc import AsyncIterator
from contextlib import asynccontextmanager

from fastapi import FastAPI
from starlette.requests import Request
from starlette.responses import Response

from fastapi_cache import FastAPICache
from fastapi_cache.backends.redis import RedisBackend
from fastapi_cache.decorator import cache

from redis import asyncio as aioredis


@asynccontextmanager
async def lifespan(_: FastAPI) -> AsyncIterator[None]:
    redis = aioredis.from_url("redis://localhost")
    FastAPICache.init(RedisBackend(redis), prefix="fastapi-cache", force=True)
    yield


app = FastAPI(lifespan=lifespan)


@cache()
async def get_cache():
    return 1


@app.get("/")
@cache(expire=60)
async def index():
    return dict(hello="world")

Initialization

First you must call FastAPICache.init during FastAPI startup; this is where you set global configuration.

init() runs once per process. A second call raises RuntimeError instead of silently keeping the first configuration: call FastAPICache.reset() before re-initializing, or pass force=True to replace it explicitly. Lifespan handlers run on every startup, so pass force=True there if the handler may run more than once in the same 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_status_header str X-FastAPI-Cache Name for the header on the response indicating if the request was served from cache; either HIT or MISS.
cache_authenticated bool None per-endpoint override for caching authenticated requests; global default is False; requires an identity-aware key_builder.

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).

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:

def request_key_builder(
    func,
    namespace: str = "",
    *,
    request: Request = None,
    response: Response = None,
    *args,
    **kwargs,
):
    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")

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.0b1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for fastapi-cache-stable 0.3.0b1
File Size Uploaded Provenance Actions
fastapi_cache_stable-0.3.0b1.tar.gz 39.3 kB With provenance Details for fastapi_cache_stable-0.3.0b1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for fastapi-cache-stable 0.3.0b1
File Interpreter ABI Platform Actions
fastapi_cache_stable-0.3.0b1-py3-none-any.whl Python 3 none any Details for fastapi_cache_stable-0.3.0b1-py3-none-any.whl

Total release size: 63.7 kB

Release files / fastapi_cache_stable-0.3.0b1.tar.gz

Download URL fastapi_cache_stable-0.3.0b1.tar.gz
Size 39.3 kB
Tags Source
SHA-256 checksum
How to use checksums
1228c548757f46f410337fd80ce5f63dfaa42e2c0decd0e277b83ddbd286ee3d
BLAKE2b-256 checksum
How to use checksums
822853d85bac579fee337626c1789a2e418b0f35f36d4149e96cc3f629162ff0
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 16, 2026.

Transparency log

Release files / fastapi_cache_stable-0.3.0b1-py3-none-any.whl

Download URL fastapi_cache_stable-0.3.0b1-py3-none-any.whl
Size 24.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
db7faf0eb34663127b67fe4e48eef580e0b3cc4f8b3a88f476f209b15bf49f51
BLAKE2b-256 checksum
How to use checksums
4d5c8d1f74c786b70f9af7cca3802aec24a8b90853b79075ca55677c84180f25
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 16, 2026.

Transparency log

Security for fastapi-cache-stable 0.3.0b1

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.

Select from 2 files

Attestation for fastapi_cache_stable-0.3.0b1.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 16, 2026.

Transparency log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page