hiredis: the C client underneath most Redis bindings

What hiredis is for, and what it deliberately leaves out

hiredis is a C client library for Redis. The README calls it minimalistic because it adds only minimal support for the protocol, and the reason to reach for it is the opposite of a feature list: it gives you a connection, a printf-style command API and a reply parser, and nothing else. The README states that it only supports the binary-safe Redis protocol, so it works with any Redis version from 1.2.0 onward.

The audience is narrow and specific. If you are writing a C or C++ service that talks to Redis, hiredis is the layer you call directly. If you are writing a Redis binding for another language, the reply parser is the piece you want: the README describes it as decoupled from the I/O layer and designed for reusability, which is why it can be embedded in higher level bindings for efficient reply parsing. That design decision explains a lot of the project's shape. The parser is a stream parser with no socket attached, so it can be fed bytes from any event loop, including ones hiredis has never heard of.

What it is not: an object mapper, a pool, a retry policy, or a cluster client. The README documents no such features, and the repository layout backs that up. The top-level entries are the library sources (hiredis.c, async.c, read.c, net.c, sds.c, alloc.c, dict.c), headers, build files and an examples directory. There is no cluster module in that listing.

Three APIs in one library: synchronous, asynchronous, reply parsing

The README names three APIs: synchronous, asynchronous and reply parsing. They are separate entry points into the same code base, not three products.

The synchronous API is small. The README lists three calls to get started: redisConnect to create a redisContext, redisCommand to send a command and read the reply, and freeReplyObject to release it. The context holds connection state, including an integer err field that is non-zero on failure and an errstr describing it. Every example in the README checks err after connecting, and that is not ceremony: a NULL context and a context with err set are different failures, and the README's snippet handles both.

For anything beyond a host and port, redisConnectWithOptions takes a redisOptions struct. The README shows helper macros for setting the endpoint (REDIS_OPTIONS_SET_TCP, REDIS_OPTIONS_SET_UNIX), a macro for attaching private data with a destructor (REDIS_OPTIONS_SET_PRIVDATA), and flags applied through the options member. Those flags include REDIS_OPT_NONBLOCK for a non-blocking connection, REDIS_OPT_REUSEADDR for SO_REUSEADDR, the address-family preferences REDIS_OPT_PREFER_IPV4, REDIS_OPT_PREFER_IPV6 and REDIS_OPT_PREFER_IP_UNSPEC, and REDIS_OPT_NO_PUSH_AUTOFREE for RESP3 push handling. The README notes hiredis prefers IPv4 by default, and that REDIS_OPT_PREFER_IP_UNSPEC passes AF_UNSPEC to getaddrinfo so both families are searched at once.

The asynchronous API is where the event loop adapters come in, and the examples directory shows how many loops the project intends to support: libevent, libev, glib, libuv, libhv, libsdevent, ivykis, Qt, plus a poll-based example and an Apple-specific one. That breadth is the strongest argument for the async API. You are not adopting hiredis's event loop; you are plugging hiredis into the loop you already run. The README also documents redisReconnect, which restores a lost connection using the same endpoint and options as the existing context.

Installing hiredis and running a first command

The repository ships both a Makefile and a CMakeLists.txt, plus pkg-config templates (hiredis.pc.in and hiredis_ssl.pc.in) and CMake package config templates. The Makefile sets PREFIX to /usr/local by default and installs headers under include/hiredis and the library under lib, with the pkg-config file in lib/pkgconfig. Building the library itself is one command:

make

That produces libhiredis from the object list in the Makefile: alloc.o, net.o, hiredis.o, sds.o, async.o, read.o and sockcompat.o. To install it under a different prefix, the Makefile exposes PREFIX and DESTDIR, so a staged install into a package root looks like this:

make
make install PREFIX=/usr DESTDIR=/tmp/stage

After installing, a C program compiles against it through pkg-config, since the Makefile installs hiredis.pc into the library's pkgconfig directory. The README's synchronous example is the shortest path to a working call, and it is worth copying verbatim the first time:

redisContext *c = redisConnect("127.0.0.1", 6379);
if (c == NULL || c->err) {
    if (c) {
        printf("Error: %s\n", c->errstr);
    } else {
        printf("Can't allocate redis context\n");
    }
}

What you should see: either a context with err equal to zero, or a context whose errstr tells you why the connection failed. The README does not document a return value convention for redisCommand beyond the reply object, so check the reply type before reading its fields. The Makefile also defines a test target that starts redis-server on port 56379 with a unix socket at /tmp/hiredis-test-redis.sock, which is a useful reference for how the project expects a test instance to be configured.

Upgrades are not free: SONAME, timeouts and RESP3 doubles

The upgrade notes are the part of this README that deserves the most attention before you pin a version. The project has a documented API and ABI history, linked from the top of the README, and the notes below it describe real breakage.

The 1.0.0 release changed struct members: redisContext gained free_privdata and privctx, redisOptions.timeout was renamed to connect_timeout with a new command_timeout added, and the createArray function in redisReplyObjectFunctions changed its length parameter from int to size_t. The README's own summary is that most applications can upgrade with minor code changes and recompiling, which is honest but still means recompiling.

The 1.1.0 note is a behavioural change, not a structural one: hiredis can now return nan in a REDIS_REPLY_DOUBLE alongside -inf and inf, and the README tells applications that deal with RESP3 doubles to account for it. If your code assumes a double reply is always a number or an infinity, that assumption is now wrong.

The prerelease note for versions after 1.2.0 changes how poll(2) is invoked while waiting for a connection. Interrupted calls are retried until the connection succeeds or fails, or until the overall connection timeout is reached. Previously an interrupted poll caused the connection to fail with c->err set to REDIS_ERR_IO and errstr set to a poll(2): Interrupted system call message. Code that treated that specific error as fatal will now rarely see it, and code that relied on the old fast-fail behaviour will wait longer instead.

There is also a version-numbering trap: the README states that v1.0.1 erroneously bumped SONAME, which is why 1.0.2 is 1.0.0 plus the fix for CVE-2021-32765 and 1.0.1 is skipped in the upgrade path. If you are matching a system library version to an upstream tag, that gap matters.

Where hiredis is the wrong choice

The limitations follow directly from the design. hiredis speaks the protocol and parses replies. It does not decide which server to talk to. Redis Cluster requires slot mapping, MOVED and ASK redirection handling, and a topology view; none of that appears in the README or the top-level file listing, and the README points to a separate release line for the latest stable documentation rather than describing cluster behaviour here. If your deployment is a cluster, hiredis alone is not the client you want.

Command construction is the second boundary. redisCommand takes a printf-style format string, which is convenient and also a place where a mistake becomes a protocol error or an injection. The README does not present the format-string API as a safety mechanism, and it should not be read as one.

Third, the async API requires you to bring an event loop and manage the callback lifecycle yourself. The examples directory shows the integrations, but integrating hiredis with your loop is your code, and the README documents no built-in reconnection policy beyond calling redisReconnect yourself. If you want pooling, retries and health checks out of the box, a higher level client in your application language will get you there faster, and it may well use hiredis underneath anyway.

hiredis versus the language clients built on top of it

The most common comparison is not against another C library. It is against the Redis clients in Python, Ruby or C++ that people already use, several of which depend on hiredis for parsing. The difference in approach is where the protocol layer sits.

In a Python or Ruby client, you call a method named after the Redis command and get back a native object. The client owns connection pooling, encoding and error translation. hiredis gives you none of that: you format the command, you read redisReply fields, and you decide what a nil bulk reply means in your program. That is more work and also less indirection, which is the trade.

Against redis-plus-plus, the split is language and abstraction level. A C++ client offers types and RAII around the same protocol; hiredis offers a C struct and manual cleanup through freeReplyObject. If your codebase is C++ and you want idiomatic ownership semantics, the C API will feel like a step down, even though it is the layer doing the parsing either way.

The repository also ships an SSL variant: ssl.c, hiredis_ssl.h and hiredis_ssl.pc.in are present at the top level, and there is an example-ssl.c and an example-libevent-ssl.c in the examples directory. That matters when the comparison is with a client that assumes plain TCP.

Licence and the cost of tracking a C library

hiredis is BSD-3-Clause, and the COPYING file at the repository root is the authoritative text. The Makefile header states the file is released under the BSD license and points at COPYING. For most commercial users a permissive licence of this kind is the reason hiredis is embeddable at all, but the obligations are yours to read; nothing here is legal advice, and the bundled sds and dict sources come from the same project tree and should be checked alongside it.

Maintenance cost is mostly upgrade cost. The library is small enough that a vendored copy is a realistic option, and the README's emphasis on a stable API and ABI history suggests that is an intended use. The catch is the same one described above: recompiling is the normal upgrade path, and the 1.0.0 member renames, the 1.1.0 nan change and the post-1.2.0 poll retry behaviour are the three points where a compile-and-ship upgrade can change runtime behaviour. The last push to the repository was on 2026-09-21, and the most recent releases listed are v1.4.1, v1.3.1 and v1.2.1, all dated 2026-08-06. Three maintenance lines receiving releases on the same day tells you the project still backports, and also that you need to pick your line deliberately rather than taking whatever your package manager offers.

Editorial conclusion

Adopt hiredis when you are writing C or C++ against Redis, or when you are building a binding in another language and want the reply parser instead of your own. Do not adopt it if you want an ORM, a connection pool, cluster slot routing or anything above the protocol: the README lists none of those, and the Redis Cluster client lives in a separate repository. Before you commit, check the API and ABI history page the README links, read the upgrade notes for 1.1.0 and 1.2.0, and confirm which SONAME your distribution packages, because the 1.0.1 release bumped it by mistake.

Frequently asked questions

Official sources

1. Issues
2. License: BSD-3-Clause
3. README
4. redis/hiredis on GitHub
5. Releases