{"library":"hiredis","title":"Hiredis Python Wrapper","description":"Hiredis is a Python wrapper for the minimalistic C client library for Redis, also named hiredis. It provides a fast, compiled response parser, significantly speeding up the parsing of Redis replies, especially multi-bulk responses. It is primarily used to boost the performance of Python Redis clients like `redis-py` by providing a faster parser. The current version is 3.3.1 and it maintains an active release cadence with frequent compatibility updates and bug fixes.","status":"active","version":"3.3.1","language":"en","source_language":"en","source_url":"https://github.com/redis/hiredis-py","tags":["redis","parser","performance","serialization","c-extension","data structures"],"install":[{"cmd":"pip install hiredis","lang":"bash","label":"Basic Installation"},{"cmd":"pip install \"redis[hiredis]\"","lang":"bash","label":"With redis-py (recommended for performance)"}],"dependencies":[{"reason":"Runtime requirement, officially >=3.8.","package":"Python","optional":false},{"reason":"Required for building from source (e.g., on Debian/Ubuntu systems).","package":"python3-dev","optional":true},{"reason":"Commonly used with the `redis-py` client library for performance parsing.","package":"redis","optional":true}],"imports":[{"note":"The primary class for parsing Redis protocol streams.","symbol":"Reader","correct":"from hiredis import Reader"}],"quickstart":{"code":"import hiredis\n\n# Create a Reader instance to parse Redis protocol data\nreader = hiredis.Reader()\n\n# Example 1: Parse a simple string reply ('+OK\\r\\n')\nreader.feed(b\"+OK\\r\\n\")\nresult_ok = reader.gets()\nprint(f\"Parsed simple string: {result_ok}\")\n\n# Example 2: Parse a bulk string reply ('$5\\r\\nhello\\r\\n')\nreader.feed(b\"$5\\r\\nhello\\r\\n\")\nresult_hello = reader.gets()\nprint(f\"Parsed bulk string: {result_hello}\")\n\n# Example 3: Parse an array reply ('*2\\r\\n$5\\r\\nhello\\r\\n$5\\r\\nworld\\r\\n')\nreader.feed(b\"*2\\r\\n$5\\r\\nhello\\r\\n$5\\r\\nworld\\r\\n\")\nresult_array = reader.gets()\nprint(f\"Parsed array: {result_array}\")\n\n# Example 4: Handle incomplete data - gets() returns False if no full reply is available\nreader.feed(b\"$6\\r\\nfoobar\")\nincomplete_result = reader.gets()\nprint(f\"Incomplete data (should be False): {incomplete_result}\")\nreader.feed(b\"\\r\\n\") # Complete the data\ncompleted_result = reader.gets()\nprint(f\"Completed data: {completed_result}\")","lang":"python","description":"This quickstart demonstrates the direct usage of `hiredis.Reader` to parse Redis protocol strings. The `feed()` method takes raw bytes, and `gets()` retrieves the next complete parsed reply. It handles different Redis data types and returns `False` if a complete reply is not yet available in the buffer."},"warnings":[{"fix":"Update your code to expect Python lists when parsing Redis SET command replies. Convert to a set explicitly if needed: `set_data = set(parsed_list_from_hiredis)`.","message":"In `hiredis` v3.0.0, the parsing of Redis Sets was changed to return Python lists instead of Python sets. This was considered a bug fix but is a breaking change for applications expecting Python set objects.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Ensure you have the necessary build tools and Python development headers. For Debian/Ubuntu, `sudo apt-get install python3-dev gcc`. For other systems, consult your package manager documentation.","message":"Installing `hiredis` from source (e.g., when a pre-built wheel is not available for your specific Python version or OS) requires Python development headers (e.g., `python3-dev` on Debian/Ubuntu) and a C compiler (like `gcc`) to be installed on your system. Without these, `pip install hiredis` might fail with compilation errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Implement robust error handling around `reader.gets()`. Catch `hiredis.ProtocolError` and re-establish your Redis connection and parser instance.","message":"When `hiredis.Reader` encounters a protocol error (e.g., due to a corrupted stream), it raises `hiredis.ProtocolError`. This indicates an unrecoverable state for the current reader instance, and the I/O code feeding data to the reader should typically reconnect or create a new reader.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your `hiredis` installation is version 3.0.0 or higher when using `redis-py` versions 5.x or later. Upgrade `hiredis` by running `pip install --upgrade hiredis`.","message":"If you are using `redis-py` version 5.x or later with an older `hiredis` version (e.g., < 3.0), `redis-py` might not correctly detect and utilize `hiredis` for parsing, leading to a `NameError: name 'hiredis' is not defined` if `redis-py` attempts to use `hiredis.pack_command` conditionally. `redis-py` version 5.x explicitly checks for `hiredis.__version__ >= 3`.","severity":"gotcha","affected_versions":"hiredis < 3.0.0 used with redis-py >= 5.x"},{"fix":"Always check the return value of `reader.gets()` for `False` to determine if more data is needed before a complete reply can be parsed. Example: `reply = reader.gets(); if reply is False: ...`.","message":"The `hiredis.Reader.gets()` method returns `False` when the internal buffer does not contain a full, complete reply. It does not raise an error or return `None` or an empty string. This behavior needs to be explicitly checked when interacting with the reader.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-05T00:00:00.000Z","next_check":"2026-07-04T00:00:00.000Z"}