node-redis is a modern, high performance Redis client for Node.js.

Learn for free at Redis University

Build faster with the Redis Launchpad

Try the Redis Cloud

Dive in developer tutorials

Join the Redis community

Work at Redis

Start a redis via docker:

To install node-redis, simply:

"redis" is the "whole in one" package that includes all the other packages. If you only need a subset of the commands, you can install the individual packages. See the list below.

Looking for a high-level library to handle object mapping? See redis-om-node!

The above code connects to localhost on port 6379. To connect to a different host or port, use a connection string in the format redis[s]://[[username][:password]@][host][:port][/db-number]:

You can also use discrete parameters, UNIX sockets, and even TLS to connect. Details can be found in the client configuration guide.

To check if the the client is connected and ready to send commands, use client.isReady which returns a boolean. client.isOpen is also available. This returns true when the client's underlying socket is open, and false when it isn't (for example when the client is still connecting or reconnecting after a network error).

There is built-in support for all of the out-of-the-box Redis commands. They are exposed using the raw Redis command names (HSET, HGETALL, etc.) and a friendlier camel-cased version (hSet, hGetAll, etc.):

Modifiers to commands are specified using a JavaScript object:

Replies will be transformed into useful data structures:

Buffers are supported as well:

For commands that return serialized binary payloads, such as DUMP, map blob strings to Buffer before using the result with commands like RESTORE:

If you want to run commands and/or use arguments that Node Redis doesn't know about (yet!) use .sendCommand():

Note: the API is different when using a cluster.

Start a transaction by calling .multi(), then chaining your commands. When you're done, call .exec() and you'll get an array back with your results:

You can also watch keys by calling .watch(). Your transaction will abort if any of the watched keys change.

In v4, RedisClient had the ability to create a pool of connections using an "Isolation Pool" on top of the "main" connection. However, there was no way to use the pool without a "main" connection:

In v5 we've extracted this pool logic into its own class—RedisClientPool:

See the Pub/Sub overview.

SCAN results can be looped over using async iterators:

This works with HSCAN, SSCAN, and ZSCAN too:

You can override the default options by providing a configuration object:

Note: CAS/CAD operations were introduced in Redis 8.4

Note: This feature requires the optional @node-rs/xxhash peer dependency.

The digest helper computes an XXH3 64-bit hash locally, matching what Redis computes via the DIGEST command. This is useful for CAS/CAD operations with large values where comparing the full value would be inefficient.

The QUIT command has been deprecated in Redis 7.2 and should now also be considered deprecated in Node-Redis. Instead of sending a QUIT command to the server, the client can simply close the network connection.

client.QUIT/quit() is replaced by client.close(). and, to avoid confusion, client.disconnect() has been renamed to client.destroy().

Node Redis v5 adds support for Client Side Caching, which enables clients to cache query results locally. The Redis server will notify the client when cached results are no longer valid.

See the V5 documentation for more details and advanced usage.

Node Redis will automatically pipeline requests that are made during the same "tick".

Of course, if you don't do something with your Promises you're certain to get unhandled Promise exceptions. To take advantage of auto-pipelining and handle your Promises, use Promise.all().

Look at the sentinel section to figure out how to use this library with sentinels.

See the Programmability overview.

Check out the Clustering Guide when using Node Redis to connect to a Redis Cluster.

Important: Initializing OpenTelemetry only enables node-redis metrics instrumentation and requires both @opentelemetry/api and an OpenTelemetry SDK configured in your application.

Important: Initialize OpenTelemetry before creating Redis clients. For SDK/provider/exporter setup, verification, and advanced configuration, see:

• OpenTelemetry Metrics docs
• OpenTelemetry Metrics example

Node Redis publishes telemetry through Node.js diagnostics_channel, enabling APM tools and custom instrumentation to observe commands, connections, and internal events. See the Diagnostics Channel guide for the full channel reference and usage examples.

The Node Redis client class is an Nodejs EventEmitter and it emits an event each time the network status changes:

⚠️ You MUST listen to error events. If a client doesn't have at least one error listener registered and an error occurs, that error will be thrown and the Node.js process will exit. See the > EventEmitter docs for more details.

The client will not emit any other events beyond those listed above.

Node Redis is supported with the following versions of Redis:

See Supported Redis Versions.

• From V3 to V4
• From V4 to V5
• V5

If you'd like to contribute, check out the contributing guide.

Thank you to all the people who already contributed to Node Redis!

This repository is licensed under the "MIT" license. See LICENSE.