redis/redis-py · error · NotImplementedError

XXHASH support requires the optional 'xxhash' library. Insta

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

digest_local() computes an XXH3 digest client-side (for IFDEQ/IFDNE flows) and depends on the optional xxhash C library. If xxhash is not installed (HAS_XXHASH is False at core.py:11-13), the method raises NotImplementedError pointing to the install command. The server-side digest() command works without this dependency.

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

Solutions

1. Install the dependency: pip install xxhash (or pip install redis[xxhash] to pin via the extra).
2. Add xxhash (or the redis[xxhash] extra) to your requirements.txt / pyproject dependencies.
3. Prefer the server-side r.digest(key) which does not need the local library, if a round-trip is acceptable.

Example fix

# before
r.digest_local(b'payload')  # NotImplementedError if xxhash missing

# after
# shell: pip install redis[xxhash]
r.digest_local(b'payload')

try:
    import xxhash  # noqa: F401
    has_xxhash = True
except ImportError:
    has_xxhash = False

if not has_xxhash:
    digest = r.digest('key')  # server-side fallback, no local dep
else:
    digest = r.digest_local(b'payload')

def has_xxhash() -> bool:
    try:
        import xxhash  # noqa: F401
        return True
    except ImportError:
        return False

try:
    d = r.digest_local(b'payload')
except NotImplementedError:
    # fall back to a server round-trip
    d = r.digest('key')

When it happens

Trigger: r.digest_local(b'value') when xxhash is not in the environment. The guard fires at core.py:3136 before any hashing.

Common situations: Fresh deploy without the redis[xxhash] extra; minimal Docker images; CI that installs bare 'redis' instead of 'redis[xxhash]'; upgrading code that started using IFDEQ/IFDNE conditional deletes.

Related errors

• Hiredis is not installed
• Maintenance notifications handlers on connection are only su
• MONITOR failed: {response}
• pubsub connection not set: did you forget to call subscribe(
• Channel: '{channel}' has no handler registered

AI-assisted analysis of redis/redis-py@da03cdc7e8 (2026-08-04). Data as JSON: /data/errors/54b4454ffc970205.json. Report an issue: GitHub.