fakeredis

2.34.1 verified Tue May 12 auth: no python install: verified quickstart: verified

Fakeredis is a pure-Python implementation of the Redis Protocol API, designed primarily for testing purposes. It provides an in-memory substitute for a real Redis server, enabling developers to run tests without requiring an external Redis instance. The library offers enhanced versions of the `redis-py` and `valkey-py` Python bindings, supporting most Redis commands, including advanced features like RedisJSON and Lua scripting. Currently at version 2.34.1, it maintains an active development status with regular updates to ensure compatibility with recent `redis-py` versions and new Redis features.

pip install fakeredis

Common errors

error ModuleNotFoundError: No module named 'fakeredis' ↓

cause The 'fakeredis' library is not installed in your current Python environment.

fix

Install the library using pip: pip install fakeredis

error ImportError: cannot import name 'FakeConnection' from 'fakeredis.aioredis' ↓

cause In `fakeredis` versions 2.33.0 and higher, `FakeConnection` was renamed or removed from `fakeredis.aioredis` without a backward-compatible alias.

fix

If using the async client, import FakeAsyncRedis directly: from fakeredis import FakeAsyncRedis. Alternatively, check the fakeredis changelog for the exact new name if you need the low-level connection object, or pin fakeredis to a version below 2.33.0.

error ModuleNotFoundError: No module named 'lupa' ↓

cause Lua scripting functionality in `fakeredis` requires the `lupa` library, which is an optional dependency and not installed by default.

fix

Install fakeredis with the lua extra: pip install fakeredis[lua]. If you are using zsh, you might need to quote the brackets: pip install 'fakeredis[lua]'.

error AttributeError: 'FakeRedis' object has no attribute 'eval' ↓

cause The `eval` (Lua scripting) command is being called on a `FakeRedis` instance, but the necessary Lua support (`lupa` library) is missing, or the specific command implementation is not available in your `fakeredis` version.

fix

Ensure fakeredis is installed with Lua support (pip install fakeredis[lua]). If the error persists, the specific Lua feature or command might not be fully implemented in fakeredis, or there could be a compatibility issue with your redis-py version.

Warnings

breaking Fakeredis versions older than 2.34.1 might encounter issues when used with `redis-py` 7.2.0 or newer, particularly concerning deprecated arguments. Ensure `fakeredis` is updated to maintain compatibility. ↓

fix Upgrade `fakeredis` to version 2.34.1 or higher: `pip install --upgrade fakeredis`.

breaking In `fakeredis` v1.0, the default behavior changed: each `FakeRedis` or `FakeStrictRedis` instance now contains its own isolated state. This means instances created without explicitly sharing a `FakeServer` will not share data. Previous versions defaulted to a shared (singleton) state. ↓

fix To achieve shared state between instances, explicitly create a `FakeServer` and pass it to each `FakeRedis` instance, e.g., `server = FakeServer(); r1 = FakeRedis(server=server); r2 = FakeRedis(server=server)`.

breaking Older `FakeAsyncRedis` versions (prior to v2.33.0) might not fully support the RESP3 protocol, which is important for newer Redis features and client-server communication. ↓

fix Upgrade `fakeredis` to version 2.33.0 or higher to ensure proper RESP3 support for `FakeAsyncRedis`: `pip install --upgrade fakeredis`.

gotcha `TcpFakeServer` for starting a threaded fake Redis server requires the `lupa` package for Lua scripting support (which includes `redis.lock.Lock` functionality). If Lua features are needed, install `fakeredis` with the `[lua]` extra. ↓

fix If using `TcpFakeServer` and Lua scripting, install with `pip install "fakeredis[lua]"`.

gotcha Fakeredis, while comprehensive, does not guarantee bit-for-bit identical behavior to a real Redis server for all edge cases or undefined behaviors (e.g., iteration order of `SCAN`/`ZSCAN`, specifics of HyperLogLog implementation, or the exact set of bugs present in a specific Redis version). ↓

fix Be aware of these known limitations; for critical integration tests requiring exact Redis behavior, consider using `Testcontainers` with a real Redis instance.

deprecated Support for `aioredis` as a separate entity from `redis-py` (specifically `redis-py` versions 4.1.2 and below) was removed. Modern `fakeredis` versions integrate async capabilities directly through `redis-py`'s unified client. ↓

fix Ensure you are using `redis-py` version 4.3 or higher, and rely on `FakeAsyncRedis` which mirrors `redis-py`'s async client functionality.

Install

pip install "fakeredis[lua]"

pip install "fakeredis[json]"

pip install "fakeredis[probabilistic]"

Install compatibility verified last tested: 2026-05-12

python os / libc variant status wheel install import disk

3.10 alpine (musl) json wheel - 0.43s 23.9M

3.10 alpine (musl) lua wheel - 0.43s 28.7M

3.10 alpine (musl) probabilistic wheel - 0.42s 23.8M

3.10 alpine (musl) fakeredis wheel - 0.44s 23.4M

3.10 alpine (musl) json - - 0.43s 23.9M

3.10 alpine (musl) lua - - 0.42s 28.6M

3.10 alpine (musl) probabilistic - - 0.42s 23.8M

3.10 alpine (musl) fakeredis - - 0.44s 23.3M

3.10 slim (glibc) json wheel 2.1s 0.31s 24M

3.10 slim (glibc) lua wheel 2.2s 0.30s 29M

3.10 slim (glibc) probabilistic wheel 2.2s 0.31s 24M

3.10 slim (glibc) fakeredis wheel 2.1s 0.31s 24M

3.10 slim (glibc) json - - 0.32s 24M

3.10 slim (glibc) lua - - 0.28s 29M

3.10 slim (glibc) probabilistic - - 0.30s 24M

3.10 slim (glibc) fakeredis - - 0.28s 24M

3.11 alpine (musl) json wheel - 0.55s 26.6M

3.11 alpine (musl) lua wheel - 0.53s 31.2M

3.11 alpine (musl) probabilistic wheel - 0.54s 26.5M

3.11 alpine (musl) fakeredis wheel - 0.51s 25.9M

3.11 alpine (musl) json - - 0.59s 26.5M

3.11 alpine (musl) lua - - 0.55s 31.2M

3.11 alpine (musl) probabilistic - - 0.57s 26.4M

3.11 alpine (musl) fakeredis - - 0.56s 25.9M

3.11 slim (glibc) json wheel 2.1s 0.47s 27M

3.11 slim (glibc) lua wheel 2.3s 0.46s 32M

3.11 slim (glibc) probabilistic wheel 2.2s 0.48s 27M

3.11 slim (glibc) fakeredis wheel 2.0s 0.47s 26M

3.11 slim (glibc) json - - 0.49s 27M

3.11 slim (glibc) lua - - 0.42s 31M

3.11 slim (glibc) probabilistic - - 0.44s 27M

3.11 slim (glibc) fakeredis - - 0.46s 26M

3.12 alpine (musl) json wheel - 0.71s 18.2M

3.12 alpine (musl) lua wheel - 0.72s 22.8M

3.12 alpine (musl) probabilistic wheel - 0.69s 18.1M

3.12 alpine (musl) fakeredis wheel - 0.82s 17.6M

3.12 alpine (musl) json - - 0.75s 18.1M

3.12 alpine (musl) lua - - 0.80s 22.7M

3.12 alpine (musl) probabilistic - - 0.75s 18.0M

3.12 alpine (musl) fakeredis - - 0.73s 17.5M

3.12 slim (glibc) json wheel 2.1s 0.73s 19M

3.12 slim (glibc) lua wheel 2.1s 0.69s 23M

3.12 slim (glibc) probabilistic wheel 2.0s 0.69s 19M

3.12 slim (glibc) fakeredis wheel 1.9s 0.69s 18M

3.12 slim (glibc) json - - 0.76s 19M

3.12 slim (glibc) lua - - 0.72s 23M

3.12 slim (glibc) probabilistic - - 0.74s 18M

3.12 slim (glibc) fakeredis - - 0.73s 18M

3.13 alpine (musl) json wheel - 0.73s 17.9M

3.13 alpine (musl) lua wheel - 0.70s 22.5M

3.13 alpine (musl) probabilistic wheel - 0.75s 17.8M

3.13 alpine (musl) fakeredis wheel - 0.75s 17.3M

3.13 alpine (musl) json - - 0.75s 17.7M

3.13 alpine (musl) lua - - 0.71s 22.3M

3.13 alpine (musl) probabilistic - - 0.74s 17.6M

3.13 alpine (musl) fakeredis - - 0.70s 17.1M

3.13 slim (glibc) json wheel 2.0s 0.71s 18M

3.13 slim (glibc) lua wheel 2.1s 0.68s 23M

3.13 slim (glibc) probabilistic wheel 2.1s 0.65s 18M

3.13 slim (glibc) fakeredis wheel 2.0s 0.67s 18M

3.13 slim (glibc) json - - 0.71s 18M

3.13 slim (glibc) lua - - 0.80s 23M

3.13 slim (glibc) probabilistic - - 0.71s 18M

3.13 slim (glibc) fakeredis - - 0.68s 18M

3.9 alpine (musl) json wheel - 0.37s 22.8M

3.9 alpine (musl) lua wheel - 0.36s 27.5M

3.9 alpine (musl) probabilistic wheel - 0.37s 22.7M

3.9 alpine (musl) fakeredis wheel - 0.36s 22.3M

3.9 alpine (musl) json - - 0.39s 22.7M

3.9 alpine (musl) lua - - 0.36s 27.5M

3.9 alpine (musl) probabilistic - - 0.38s 22.7M

3.9 alpine (musl) fakeredis - - 0.37s 22.2M

3.9 slim (glibc) json wheel 2.4s 0.34s 23M

3.9 slim (glibc) lua wheel 2.8s 0.36s 28M

3.9 slim (glibc) probabilistic wheel 2.5s 0.36s 23M

3.9 slim (glibc) fakeredis wheel 2.5s 0.34s 23M

3.9 slim (glibc) json - - 0.34s 23M

3.9 slim (glibc) lua - - 0.32s 28M

3.9 slim (glibc) probabilistic - - 0.32s 23M

3.9 slim (glibc) fakeredis - - 0.31s 23M

Imports

FakeRedis
```
from fakeredis import FakeRedis
```
FakeStrictRedis
```
from fakeredis import FakeStrictRedis
```
Equivalent to FakeRedis in modern versions, but historically a distinct class reflecting redis-py's StrictRedis. Both are subclasses of Redis.
FakeAsyncRedis
```
from fakeredis import FakeAsyncRedis
```
FakeServer
```
from fakeredis import FakeServer
```
Used to share state between multiple FakeRedis instances; a new one is created implicitly if not provided.
TcpFakeServer
```
from fakeredis import TcpFakeServer
```
For starting a fake Redis server on a separate thread/socket.

Quickstart verified last tested: 2026-04-24

Initialize `FakeRedis` for synchronous operations or `FakeAsyncRedis` for `asyncio` based applications. These instances mimic the `redis-py` client interface, allowing you to interact with an in-memory Redis store. By default, each instance manages its own isolated state.

import fakeredis

# Basic synchronous usage
r_sync = fakeredis.FakeRedis()
r_sync.set('mykey', 'myvalue')
print(f"Synchronous get: {r_sync.get('mykey')}")

# Basic asynchronous usage
import asyncio

async def async_example():
    r_async = fakeredis.FakeAsyncRedis()
    await r_async.set('myasync_key', 'myasync_value')
    print(f"Asynchronous get: {await r_async.get('myasync_key')}")

if __name__ == '__main__':
    asyncio.run(async_example())