Install & Compatibility
Where this runs
tested against v4.0.0 · 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.000s · 36.8MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 3.4s · import 0.000s · 37MB
35MB installed
● package 35MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
redisdb
✓ def test_something(redisdb):
pytest automatically discovers and injects the `redisdb` fixture.
redis_proc
✓ def test_something_with_proc(redis_proc):
pytest automatically discovers and injects the `redis_proc` fixture for a session-scoped Redis process.
redis_noproc
✓ def test_something_with_noproc(redis_noproc):
pytest automatically discovers and injects the `redis_noproc` fixture for connecting to an existing Redis instance.
factories
✓ from pytest_redis import factories
✗ import pytest_redis.factories
It is conventional to import `factories` directly for creating custom Redis fixtures.
This quickstart demonstrates how to use the built-in `redisdb` fixture for basic Redis operations within a test. It also illustrates how to create and use custom, named Redis process and client fixtures using `pytest_redis.factories` to allow for specific configurations (like a custom port) or different scopes. Run with `pytest` after installing `pytest-redis` and `redis` client.
import pytest
from redis import Redis
from pytest_redis import factories
import os
# Basic test using the default function-scoped redisdb fixture
def test_can_connect(redisdb: Redis):
# Ensure environment variables for Redis connection (if needed by redis-py)
# are not hardcoded in actual tests, though pytest-redis manages the server.
# For direct Redis client instantiation, you might do:
# client = Redis(host=os.environ.get('REDIS_HOST', 'localhost'),
# port=int(os.environ.get('REDIS_PORT', '6379')))
redisdb.set("ping", "pong")
assert redisdb.get("ping") == b"pong"
print(f"Redis DB size: {redisdb.dbsize()}")
# Creating custom fixtures using factories
# Example: A session-scoped Redis process with a specific port or configuration
custom_redis_proc = factories.redis_proc(port=6380)
# A client fixture that uses the custom process
# Note: The string 'custom_redis_proc' matches the variable name of the proc fixture
custom_redis_client = factories.redisdb('custom_redis_proc')
# Test using the custom client fixture
def test_custom_redis_instance(custom_redis_client: Redis):
custom_redis_client.set("mykey", "myvalue")
assert custom_redis_client.get("mykey") == b"myvalue"
assert custom_redis_client.info()['tcp_port'] == 6380
Debug
Known issues
gotchaThe `redis-server` executable must be available in your system's PATH, or its path must be explicitly provided via the `--redis-exec` command-line option for pytest. Failure to do so will result in a `RedisMisconfigured` error during test collection.fixEnsure `redis-server` is installed and accessible via PATH, or run `pytest --redis-exec /path/to/redis-server`.
affects: All
gotchaWhen running tests in parallel, `pytest-redis` uses different Redis databases (DB 0-15) to isolate tests. However, using `FLUSHALL` in your tests will clear *all* databases, breaking test isolation and causing unexpected failures in parallel runs.fixAvoid `FLUSHALL` in tests. Prefer `FLUSHDB` (which clears only the currently selected database) or ensure your tests use distinct keyspaces if `FLUSHDB` is not sufficient for isolation.
affects: All
breakingUsers should be aware of breaking changes in `redis-py` versions (e.g., `redis-py` 4.0.0+). These can affect how you interact with the `redisdb` client yielded by `pytest-redis` fixtures. Notable changes include argument order for commands like `SETEX` and `LREM`, return types for `TTL`/`PTTL`, and the default handling of `decode_responses`.fixConsult the `redis-py` changelog for the version you are using. Adjust client interactions (e.g., parameter order, decoding bytes to strings) accordingly. If encountering issues, consider pinning `redis-py` to a known compatible version (e.g., `<4.4.0` as per some reports).
affects: redis-py >=4.0.0
Errors
Common errors & fixes
pytest_redis.exceptions.RedisMisconfigured: Could not find redis-server executable.
The `redis-server` executable is not found in the system's PATH or was not explicitly provided to pytest.
fixInstall Redis server, add its directory to your system's PATH environment variable, or run pytest with the `--redis-exec /path/to/redis-server` option.
TypeError: int() argument must be a string, a bytes-like object or a number, not 'NoneType' (often seen with redis-py client methods)
This typically occurs when `redis-py` (the underlying Redis client library) returns `None` for operations that previously returned an `int` or a byte string, especially after upgrading `redis-py` to version 4.x or higher, or due to incorrect `decode_responses` handling.
fixCheck the `redis-py` documentation for the specific command causing the error. Ensure you are handling `bytes` vs. `str` correctly, potentially by passing `decode_responses=True` when creating a `redis.Redis` client (or when using `factories.redisdb` if it supports it), or explicitly decoding responses. Pin `redis-py` to a specific version if necessary, e.g., `redis<4.4.0`.
Upgrade
Version history
4.0.0latest on PyPI · released Feb 28, 2026
Audit
Dependencies
pytestrequiredCore testing framework, pytest-redis is a plugin for it.
redisrequiredRedis Python client (redis-py) is needed to interact with the Redis instances provided by pytest-redis fixtures. This is a peer dependency.