Guide · Open source

How to use node-redis: install, connect and run Redis commands

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

node-redis is an open-source client library that lets Node.js programs connect to a Redis server and run its commands, such as storing and reading keys. Redis is a data store often used for caching and fast temporary data. This guide walks you through installing the package, connecting, running commands, and using transactions and pub/sub, so you can start reading and writing Redis data from a Node.js application.

node-redisredis/node-redis · ★ 17.6k · MIT Install options & downloads

Quick start

1Check prerequisites. Confirm Node.js and npm are installed and that you have a Redis server to connect to.
2Start Redis. Run the Docker command from the README to start a Redis server on port 6379.
3Install the package. Run npm install redis in your project folder.
4Connect the client. Call createClient(), add an error handler, and call connect().
5Run commands. Use set and get, or the raw and camel-cased command forms, to read and write data.
6Close the connection. Call client.destroy() when your program is finished with the client.

What you need before you start

node-redis needs three things: Node.js, npm, and a running Redis server. The library cannot do anything on its own because it has to connect to a Redis server.

The README starts a Redis server with Docker, so Docker is the easiest route if you do not already have Redis installed.

Node.js
npm
A running Redis server (the README uses Docker to run one)

Start a Redis server

Run the following command to start a Redis server in Docker. It maps port 6379 on your machine to the container, which is the default Redis port the client connects to.

docker run -p 6379:6379 -d redis:8.0-rc1

Install the node-redis package

Install the package with npm from your project folder. The package name is redis. It includes all the other packages in the project.

If you only need a subset of the commands, you can install the individual packages listed in the README, such as @redis/client for the base clients.

npm install redis

Connect and run your first commands

Import createClient, connect to the server, store a key, read it back, and close the connection. The example below uses ES module syntax. The code connects to localhost on port 6379 by default.

If your project does not use "type": "module" in package.json, use the CommonJS version of the same example, which wraps the code in an async function.

import { createClient } from "redis";

const client = await createClient()
  .on("error", (err) => console.log("Redis Client Error", err))
  .connect();

await client.set("key", "value");
const value = await client.get("key");
console.log(value); // 'value'
client.destroy();

Connect to a different server

To connect to another host or port, pass a connection string in the format redis[s]://[[username][:password]@][host][:port][/db-number]. The README also says you can use discrete parameters, UNIX sockets and TLS. Details are in the client configuration guide linked from the README.

To check the connection state, use client.isReady, which returns a boolean, or client.isOpen, which is true when the underlying socket is open.

createClient({
  url: "redis://alice:foobared@awesome.redis.server:6380",
});

Use Redis commands in raw or camel-case form

Every built-in Redis command is available under its raw name, such as HSET and HGETALL, and under a camel-cased JavaScript name, such as hSet and hGetAll. Modifiers such as EX and NX are passed as a JavaScript object.

Commands that take several values, such as DEL, HDEL or LPUSH, accept a single value or an array. Do not spread values into separate arguments, because only the first value is sent and the rest are silently ignored.

Replies are converted to JavaScript data structures. For example, hGetAll returns an object and hVals returns an array.

Pass several values as an array, not as spread arguments.
Use sendCommand() for commands or arguments the library does not know about yet.

await client.HSET("key", "field", "value");
await client.HGETALL("key");

await client.hSet("key", "field", "value");
await client.hGetAll("key");

await client.set("key", "value", {
  EX: 10,
  NX: true,
});

await client.hDel("key", ["field1", "field2"]);

Run transactions and watch keys

Start a transaction with .multi(), chain your commands, then call .exec(). You get an array with one result per command. Call .watch() on keys first if you want the transaction to abort when any watched key changes.

const [setKeyReply, otherKeyValue] = await client
  .multi()
  .set("key", "value")
  .get("another-key")
  .exec();

Pub/Sub, blocking commands and scanning

The README covers pub/sub in a separate overview document, which you should read before building messaging features. For blocking commands, version 5 moved the connection pool into its own class, RedisClientPool, so you can use the pool without a main connection.

To loop over SCAN results, use async iterators, as described in the README's Scan Iterator section.

const pool = await createClientPool()
  .on("error", (err) => console.error(err))
  .connect();

await pool.ping();

What people use it for

Reading and writing key-value data from a Node.js application
Caching or session storage on top of a Redis server
Running transactions that group several commands with .multi() and .exec()
Using optional add-on packages for Redis JSON, search or time-series data

Frequently asked questions

Is node-redis free to use?

node-redis is released under the MIT licence, according to the project page. You can check the LICENSE file in the repository for the full terms.

Does node-redis need a Redis server?

Yes. The library connects to a running Redis server and cannot run commands without one. The README uses Docker to start a server with the command shown in this guide.

How do I install node-redis?

Run npm install redis in your project folder. The redis package includes all the other packages, and you can install individual packages if you only need some commands.

How is node-redis different from ioredis?

This source does not compare node-redis with ioredis, so it cannot say which is faster or easier. ioredis is listed as a comparable project, and you can test both against your own use case.

Can node-redis connect to a Redis cluster or use TLS?

The project says it supports connections to clusters, TLS and UNIX sockets. The client configuration guide in the docs explains how to set these up.

Is there a graphical admin tool for node-redis?

No. node-redis is a code library with no user interface, so it is not a Redis admin tool. Use it inside your Node.js code, not as a visual browser for keys.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

node-redis suits Node.js developers who need to read and write Redis data from application code, including caching, sessions, transactions and pub/sub. It is not a good fit if you want a graphical admin tool, an object-mapping layer (the README points to redis-om-node for that), or if you cannot run a Redis server.

Install options & downloads