Install & Compatibility
Where this runs
tested against v3.4.1 · 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.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 23.6MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 1.9s · import 0.000s · 24MB
22MB installed
● package 22MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Reader
✓ from hiredis import Reader
The primary class for parsing Redis protocol streams.
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.
import hiredis
# Create a Reader instance to parse Redis protocol data
reader = hiredis.Reader()
# Example 1: Parse a simple string reply ('+OK\r\n')
reader.feed(b"+OK\r\n")
result_ok = reader.gets()
print(f"Parsed simple string: {result_ok}")
# Example 2: Parse a bulk string reply ('$5\r\nhello\r\n')
reader.feed(b"$5\r\nhello\r\n")
result_hello = reader.gets()
print(f"Parsed bulk string: {result_hello}")
# Example 3: Parse an array reply ('*2\r\n$5\r\nhello\r\n$5\r\nworld\r\n')
reader.feed(b"*2\r\n$5\r\nhello\r\n$5\r\nworld\r\n")
result_array = reader.gets()
print(f"Parsed array: {result_array}")
# Example 4: Handle incomplete data - gets() returns False if no full reply is available
reader.feed(b"$6\r\nfoobar")
incomplete_result = reader.gets()
print(f"Incomplete data (should be False): {incomplete_result}")
reader.feed(b"\r\n") # Complete the data
completed_result = reader.gets()
print(f"Completed data: {completed_result}")
Debug
Known issues
breakingIn `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.fixUpdate 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)`.
affects: >=3.0.0
gotchaInstalling `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.fixEnsure 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.
affects: All versions
gotchaWhen `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.fixImplement robust error handling around `reader.gets()`. Catch `hiredis.ProtocolError` and re-establish your Redis connection and parser instance.
affects: All versions
gotchaIf 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`.fixEnsure 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`.
affects: hiredis < 3.0.0 used with redis-py >= 5.x
gotchaThe `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.fixAlways 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: ...`.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'hiredis'
The Python `hiredis` package is not installed in the current Python environment, or the environment where it's installed is not active.
error: Microsoft Visual C++ 14.0 or greater is required.
When installing `hiredis` on Windows, Python needs a C/C++ compiler to build the C extensions. This error indicates that the necessary Microsoft Visual C++ Build Tools are missing.
fixDownload and install the 'Microsoft C++ Build Tools' from the Visual Studio website.
fatal error: 'hiredis/hiredis.h' file not found
This error occurs when a C/C++ application or another Python package's C extension attempts to compile against the `hiredis` C library, but the header files (e.g., `hiredis.h`) are not found by the compiler.
fixInstall the development package for the `hiredis` C library. For Debian/Ubuntu: `sudo apt-get install libhiredis-dev`. For CentOS/RHEL: `sudo yum install hiredis-devel`. For macOS: `brew install hiredis`.
error while loading shared libraries: libhiredis.so: cannot open shared object file: No such file or directory
This runtime error indicates that the dynamic linker cannot find the `hiredis` shared library (`libhiredis.so` on Linux, `.dylib` on macOS, `.dll` on Windows) when trying to run an application that depends on it.
fixEnsure the `hiredis` C library is installed and its installation directory is in the system's library search path. On Linux, run `sudo ldconfig` after installation or add the library path to `/etc/ld.so.conf.d/` and then `sudo ldconfig`. You might also temporarily set `LD_LIBRARY_PATH`.
NameError: name 'hiredis' is not defined (in redis-py versions 5.0+)
Recent versions of `redis-py` (5.0 and newer) require `hiredis` version 3.0 or higher for its optimized parser. If an older version of `hiredis` is installed, `redis-py` might fail to load it correctly, leading to this `NameError`.
fixUpgrade your `hiredis` Python package to version 3.0 or newer: `pip install --upgrade hiredis`.
Upgrade
Version history
3.4.1latest on PyPI · released Aug 7, 2026
Audit
Dependencies
PythonrequiredRuntime requirement, officially >=3.8.
python3-devoptionalRequired for building from source (e.g., on Debian/Ubuntu systems).
redisoptionalCommonly used with the `redis-py` client library for performance parsing.