Install & Compatibility
Where this runs
tested against v2.37.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.587s · 30.1MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.3s · import 0.513s · 31MB
28MB installed
● package 28MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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())
Debug
Known issues
breakingFakeredis 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.fixUpgrade `fakeredis` to version 2.34.1 or higher: `pip install --upgrade fakeredis`.
affects: <2.34.1
breakingIn `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.fixTo 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)`.
affects: <1.0
breakingOlder `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.fixUpgrade `fakeredis` to version 2.33.0 or higher to ensure proper RESP3 support for `FakeAsyncRedis`: `pip install --upgrade fakeredis`.
affects: <2.33.0
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.fixIf using `TcpFakeServer` and Lua scripting, install with `pip install "fakeredis[lua]"`.
affects: All versions
gotchaFakeredis, 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).fixBe aware of these known limitations; for critical integration tests requiring exact Redis behavior, consider using `Testcontainers` with a real Redis instance.
affects: All versions
deprecatedSupport 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.fixEnsure you are using `redis-py` version 4.3 or higher, and rely on `FakeAsyncRedis` which mirrors `redis-py`'s async client functionality.
affects: Prior to v2.34.0 (for `aioredis` separation)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'fakeredis'
The 'fakeredis' library is not installed in your current Python environment.
fixInstall the library using pip: `pip install fakeredis`
ImportError: cannot import name 'FakeConnection' from 'fakeredis.aioredis'
In `fakeredis` versions 2.33.0 and higher, `FakeConnection` was renamed or removed from `fakeredis.aioredis` without a backward-compatible alias.
fixIf 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.
ModuleNotFoundError: No module named 'lupa'
Lua scripting functionality in `fakeredis` requires the `lupa` library, which is an optional dependency and not installed by default.
fixInstall `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]'`.
AttributeError: 'FakeRedis' object has no attribute 'eval'
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.
fixEnsure `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.
Upgrade
Version history
2.37.1latest on PyPI · released Aug 18, 2026
Audit
Dependencies
redis>=4.3requiredRequired for core Redis API compatibility.
sortedcontainers>=2requiredRequired for core functionality.
typing-extensions~=4.7requiredRequired for core functionality.
lupa>=2.1optionalOptional, required for Lua scripting support (e.g., Redis Lock commands) when installed with `[lua]` extra.
jsonpath-ng>=1.6optionalOptional, required for RedisJSON commands when installed with `[json]` extra.
pyprobables>=0.6optionalOptional, required for probabilistic data structures (BloomFilter, CuckooFilter, CountMinSketch) when installed with `[probabilistic]` extra.