redis/redis-py · error · NotImplementedError

XXHASH support requires the optional 'xxhash' library…

Error message

XXHASH support requires the optional 'xxhash' library. Install it with 'pip install xxhash' or use this package's extra with 'pip install redis[xxhash]' to enable this feature.

What it means

Raised as `NotImplementedError` by `digest_local()` (redis/commands/core.py:3136) when `HAS_XXHASH` is False, i.e. the optional `xxhash` package is not installed. The method computes an XXH3 hex digest client-side (for IFDEQ/IFDNE conditionals) and the C extension is required for that.

Solutions

  1. Install the extra: `pip install redis[xxhash]` (or directly `pip install xxhash`).
  2. Pin `xxhash` in your requirements if you use `digest_local`, `ifdeq`, or `ifdne` flows.
  3. If you cannot add the dependency, use server-side `digest()` (DIGEST command) or plain `ifeq`/`ifne` instead.

Example fix

// before: NotImplementedError at runtime
val = r.digest_local(b'x')
// after (shell)
// pip install redis[xxhash]
// then
val = r.digest_local(b'x')
Defensive patterns

Strategy: try-catch

Validate before calling

try:
    import xxhash  # noqa: F401
    HAS_XXHASH = True
except ImportError:
    HAS_XXHASH = False
if not HAS_XXHASH:
    raise RuntimeError('xxhash not installed; pip install redis[xxhash]')
r.digest_local(b'x')

Try / catch

try:
    digest = r.digest_local(value)
except NotImplementedError:
    # fall back to server-side DIGEST or plain ifeq/ifne
    digest = r.digest(name)

Prevention

When it happens

Trigger: Calling `r.digest_local(value)` in an environment where `xxhash` is not installed (the `redis[xxhash]` extra was not pulled in).

Common situations: Fresh checkout without installing extras; slim Docker images that `pip install redis` without extras; CI matrices that don't include the xxhash extra; upgrading redis-py and starting to use the new experimental digest API.

Related errors

AI-assisted analysis of redis/redis-py@6a6b581b48 (2026-08-10). Data as JSON: /api/errors/54b4454ffc970205. Report an issue: GitHub.

Appendix: source

Thrown at redis/commands/core.py:3137

        This is useful for conditional operations like IFDEQ/IFDNE where you need to
        compute the digest client-side before sending a command.

        Warning:
        **Experimental** - This API may change or be removed without notice.

        Arguments:
          - value: Union[bytes, str] - the value to compute the digest of.
            If a string is provided, it will be encoded using UTF-8 before hashing,
            which matches Redis's default encoding behavior.

        Returns:
          - (str | bytes) the XXH3 digest of the value as a hex string (16 hex characters).
            Returns bytes if decode_responses is False, otherwise returns str.

        For more information, see https://redis.io/commands/digest
        """
        if not HAS_XXHASH:
            raise NotImplementedError(
                "XXHASH support requires the optional 'xxhash' library. "
                "Install it with 'pip install xxhash' or use this package's extra with "
                "'pip install redis[xxhash]' to enable this feature."
            )

        local_digest = xxhash.xxh3_64(value).hexdigest()

        # To align with digest, we want to return bytes if decode_responses is False.
        # The following works because of Python's mixin-based client class hierarchy.
        if not self.get_encoder().decode_responses:
            local_digest = local_digest.encode()

        return local_digest

    @overload
    def digest(self: SyncClientProtocol, name: KeyT) -> str | bytes | None: ...

    @overload

View on GitHub (pinned to 6a6b581b48)