libvalkey

library4.1.0pypypi✓ verified 24d ago

libvalkey-py is a Python extension that wraps the protocol parsing code from the underlying libvalkey C library. It primarily speeds up the parsing of multi bulk replies from a Valkey server. The library is actively maintained, with its current version being 4.0.1, and releases occurring regularly to introduce new features, improvements, and bug fixes.

database

pip install libvalkey

github ↗package ↗homepage ↗changelog ↗

INSTALL

IMPORT

SIG · LIBVALKEY

libvalkey

databasepythonv4.1.0

Install

1.6s avg

Import

—

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v4.1.0 · 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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.000s · 18.2MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.000s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Reader

✓ from libvalkey import Reader

✗ import hiredis

The library was renamed from `hiredis-py` to `libvalkey-py` in version 3.0.0. Direct imports of `hiredis` will fail in `libvalkey-py` versions 3.0.0 and above.

The quickstart demonstrates how to initialize the `Reader` class, feed raw Valkey protocol bytes, and retrieve parsed replies. It also shows how to handle cases where insufficient data is fed, using a custom sentinel value.

import libvalkey # The Reader class is responsible for parsing replies from a stream of data. # It does not handle I/O itself. reader = libvalkey.Reader() # Feed raw Valkey protocol bytes to the reader reader.feed(b"$5\r\nhello\r\n") # Retrieve the parsed reply reply = reader.gets() print(f"Parsed reply: {reply}") # Example with a list reply reader.feed(b"*2\r\n$5\r\nhello\r\n$5\r\nworld\r\n") list_reply = reader.gets() print(f"Parsed list reply: {list_reply}") # Example with custom sentinel for 'not enough data' reader_ellipsis = libvalkey.Reader(notEnoughData=Ellipsis) reader_ellipsis.feed(b"*2\r\n$5\r\nhello\r\n") partial_reply = reader_ellipsis.gets() print(f"Partial reply (needs more data): {partial_reply}") reader_ellipsis.feed(b"$5\r\nworld\r\n") full_reply = reader_ellipsis.gets() print(f"Full reply: {full_reply}")

Debug

Known issues

breakingThe library was renamed from `hiredis-py` to `libvalkey-py` in version 3.0.0. All `hiredis` imports must be updated to `libvalkey`.

fix

Change `import hiredis` to `import libvalkey` and update any references to `hiredis.Reader` to `libvalkey.Reader`.

affects: >=3.0.0

gotchaBuilding `libvalkey` from source (e.g., if a pre-compiled wheel is not available for your environment) requires Python development headers (e.g., `python3-dev` on Debian/Ubuntu) and a C compiler like `gcc`.

fix

Ensure `python3-dev` and `gcc` (or equivalent build tools for your OS) are installed before attempting `pip install libvalkey` if pre-built wheels are not available. For example, `sudo apt-get install python3-dev gcc` on Debian/Ubuntu.

affects: All versions

gotchaFor error handling, `libvalkey.ProtocolError` is raised for invalid protocol states. However, `libvalkey.ReplyError` (for server-side error replies like `-ERR`) is *returned* by `gets()` and not raised as an exception by default.

fix

Explicitly check the return value of `reader.gets()` for instances of `libvalkey.ReplyError` if you want to handle server-generated errors. For example: `reply = reader.gets(); if isinstance(reply, libvalkey.ReplyError): handle_error(reply)`.

affects: All versions

gotchaWhen `libvalkey.Reader` is initialized with an `encoding` (e.g., 'utf-8'), bulk string replies are decoded. If the decoding fails and the `errors` parameter is set to 'strict' (the default), a `UnicodeDecodeError` will be raised.

fix

To handle decoding errors gracefully, initialize the `Reader` with a different `errors` handler, such as 'ignore', 'replace', or 'backslashreplace' (e.g., `libvalkey.Reader(encoding='utf-8', errors='replace')`).

affects: All versions

breakingVersion 4.0.0 included changes to the `Reader`'s behavior, with a subsequent patch (v4.0.0b1) to 'partly restore the previous behaviour'. Users upgrading to or through v4.0.0 should review the changelog carefully for potential subtle changes in parsing logic.

fix

Thoroughly test existing code relying on `Reader` behavior when upgrading to v4.0.0 or later to ensure parsing logic remains consistent with expectations. Refer to the GitHub releases for specific changes.

affects: 4.0.0, 4.0.0b1+

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'libvalkey'

The 'libvalkey' Python package is not installed in the current environment or is not accessible on the Python path.

fix

Install the library using pip: `pip install libvalkey`

libvalkey.ProtocolError

A protocol error occurred, typically due to a corrupt data stream from the Valkey server or multiple threads attempting to use the same socket for I/O, leading to inconsistent data parsing.

fix

Ensure thread safety by using separate `libvalkey.Reader` instances per thread, or re-establish the connection to the Valkey server and the `Reader` instance.

UnicodeDecodeError: 'utf-8' codec can't decode byte...

The `libvalkey.Reader` attempted to decode bulk data from the Valkey server using an incorrect or default encoding (like 'utf-8'), and the received bytes could not be interpreted with that encoding.

fix

Specify the correct encoding (e.g., 'latin-1' or the actual encoding used by your Valkey data) and an appropriate error handler when initializing the `Reader`: `reader = libvalkey.Reader(encoding='your_encoding', errors='replace')`.

error: command 'gcc' failed with exit status 1 (during pip install libvalkey)

The installation of 'libvalkey' failed because it requires compiling C extensions, and a C compiler (like `gcc`) or Python development headers are missing on the system.

fix

Install a C compiler (e.g., `sudo apt-get install build-essential` on Debian/Ubuntu, or Xcode Command Line Tools on macOS) and Python development headers (e.g., `sudo apt-get install python3-dev` on Debian/Ubuntu).

libvalkey.ReplyError: ERR unknown command 'XXXX'

The Valkey server returned an error reply (e.g., `-ERR`) indicating an issue with the executed command, such as an unknown command, invalid arguments, or a server-side problem.

fix

Check the command being sent to the Valkey server for syntax errors, incorrect command names, or invalid arguments. Ensure the Valkey server version supports the command being used. The error message following `ERR` provides specific details from the server.

Upgrade

Version history

4.1.0latest on PyPI · released Jul 18, 2026

Audit

Dependencies

python3-devoptionalRequired for building from source; typically pre-compiled wheels are available.

gccoptionalRequired for building from source; typically pre-compiled wheels are available.

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/valkey-io/libvalkey-py ↗

packagehttps://pypi.org/project/libvalkey/ ↗

homepagehttps://valkey.io ↗

changeloghttps://github.com/valkey-io/libvalkey-py/releases ↗