{"id":"54b4454ffc970205","repo":"redis/redis-py","slug":"xxhash-support-requires-the-optional-xxhash-libr","errorCode":null,"errorMessage":"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.","messagePattern":"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\\.","errorType":"exception","errorClass":"NotImplementedError","httpStatus":null,"severity":"error","filePath":"redis/commands/core.py","lineNumber":3137,"sourceCode":"        This is useful for conditional operations like IFDEQ/IFDNE where you need to\n        compute the digest client-side before sending a command.\n\n        Warning:\n        **Experimental** - This API may change or be removed without notice.\n\n        Arguments:\n          - value: Union[bytes, str] - the value to compute the digest of.\n            If a string is provided, it will be encoded using UTF-8 before hashing,\n            which matches Redis's default encoding behavior.\n\n        Returns:\n          - (str | bytes) the XXH3 digest of the value as a hex string (16 hex characters).\n            Returns bytes if decode_responses is False, otherwise returns str.\n\n        For more information, see https://redis.io/commands/digest\n        \"\"\"\n        if not HAS_XXHASH:\n            raise NotImplementedError(\n                \"XXHASH support requires the optional 'xxhash' library. \"\n                \"Install it with 'pip install xxhash' or use this package's extra with \"\n                \"'pip install redis[xxhash]' to enable this feature.\"\n            )\n\n        local_digest = xxhash.xxh3_64(value).hexdigest()\n\n        # To align with digest, we want to return bytes if decode_responses is False.\n        # The following works because of Python's mixin-based client class hierarchy.\n        if not self.get_encoder().decode_responses:\n            local_digest = local_digest.encode()\n\n        return local_digest\n\n    @overload\n    def digest(self: SyncClientProtocol, name: KeyT) -> str | bytes | None: ...\n\n    @overload","sourceCodeStart":3119,"sourceCodeEnd":3155,"githubUrl":"https://github.com/redis/redis-py/blob/da03cdc7e8731092b13e395605c3c1fb2de25de1/redis/commands/core.py#L3119-L3155","documentation":"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.","triggerScenarios":"r.digest_local(b'value') when xxhash is not in the environment. The guard fires at core.py:3136 before any hashing.","commonSituations":"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.","solutions":["Install the dependency: pip install xxhash (or pip install redis[xxhash] to pin via the extra).","Add xxhash (or the redis[xxhash] extra) to your requirements.txt / pyproject dependencies.","Prefer the server-side r.digest(key) which does not need the local library, if a round-trip is acceptable."],"exampleFix":"# before\nr.digest_local(b'payload')  # NotImplementedError if xxhash missing\n\n# after\n# shell: pip install redis[xxhash]\nr.digest_local(b'payload')","handlingStrategy":"fallback","validationCode":"try:\n    import xxhash  # noqa: F401\n    has_xxhash = True\nexcept ImportError:\n    has_xxhash = False\n\nif not has_xxhash:\n    digest = r.digest('key')  # server-side fallback, no local dep\nelse:\n    digest = r.digest_local(b'payload')","typeGuard":"def has_xxhash() -> bool:\n    try:\n        import xxhash  # noqa: F401\n        return True\n    except ImportError:\n        return False","tryCatchPattern":"try:\n    d = r.digest_local(b'payload')\nexcept NotImplementedError:\n    # fall back to a server round-trip\n    d = r.digest('key')","preventionTips":["Pin redis[xxhash] in your dependencies if you use IFDEQ/IFDNE flows.","Use server-side digest() when the local library is unavailable to avoid the hard dependency."],"tags":["redis","dependency","xxhash","optional-feature","digest"],"analyzedSha":"da03cdc7e8731092b13e395605c3c1fb2de25de1","analyzedAt":"2026-08-04T20:26:47.563Z","schemaVersion":2}