Guide · Open source
How to use ioredis: install, connect and run Redis commands in Node.js
Updated · written with AI from the project's own documentation and checked against our catalogue data
ioredis is a Redis client library for Node.js. It lets your JavaScript or TypeScript code send commands to a Redis server and read the results, using either callbacks or promises. This guide shows you how to install it, connect to Redis, run basic commands and set up a simple Pub/Sub publisher and subscriber.
ioredisredis/ioredis · ★ 15.4k · MIT Install options & downloads Quick start
- 1Check prerequisites. Confirm you have Node.js 20 or newer and a Redis server running on localhost:6379, or note its host and port.
- 2Install the package. Run npm install ioredis in your project folder.
- 3Create a client. Require ioredis and call new Redis() to connect to the default address, or pass your own host, port or connection string.
- 4Run a command. Call a lowercase Redis command method such as set or get. Use .then() for a promise or pass a callback.
- 5Add Pub/Sub if needed. Use publish in one process and subscribe in another to pass messages between them over named channels.
What you need before you install ioredis
You need Node.js 20 or newer for version 6 of ioredis, according to the README's version table. You also need a running Redis server. By default, ioredis connects to localhost:6379, so a Redis server on that address works without extra configuration.
- Node.js 20 or newer (for v6)
- A running Redis server, default localhost:6379
How do you install ioredis with npm?
Install the library from the command line with npm. In a TypeScript project, you can also add Node.js type declarations as a development dependency.
npm install ioredis
# Optional, in a TypeScript project:
npm install --save-dev @types/nodeHow do you connect to Redis and run a command?
When you create a new Redis instance, it opens a connection right away. With no arguments it connects to 127.0.0.1:6379. Commands return a promise by default, and you can also pass a callback as the last argument. Every Redis command is available as a lowercase method, and its arguments are passed straight to the server.
ioredis also accepts a connection string. Use a redis:// URL, or a rediss:// URL when you want TLS encryption.
- Use new Redis() for the default localhost:6379 connection.
- Pass a port and host, for example new Redis(6379, "192.168.1.1").
- Pass an options object with host, port, username, password and db.
- Use a redis:// or rediss:// URL to connect with one string.
const Redis = require("ioredis");
const redis = new Redis();
redis.set("mykey", "value");
redis.get("mykey").then((result) => {
console.log(result); // Prints "value"
});How do you use Pub/Sub with ioredis?
Redis Pub/Sub lets publishers send messages to named channels without knowing which subscribers, if any, are listening. ioredis uses Node.js's built-in events module to make this simple. The README example uses two files: publisher.js publishes messages to a channel, and subscriber.js listens on specific channels.
- publisher.js calls redis.publish on a channel name.
- subscriber.js calls redis.subscribe with one or more channel names.
// publisher.js
const Redis = require("ioredis");
const redis = new Redis();
redis.publish("my-channel-1", JSON.stringify({ foo: Math.random() }));What else does ioredis support?
The README lists support for Redis Cluster, Sentinel, Streams, pipelining, Lua scripting, Redis Functions, TLS, ACL, binary data and autopipelining. The library is written in TypeScript and ships its own declarations. More examples are in the examples/ folder of the repository, covering TTL, strings, hashes, lists, sets, sorted sets and streams.
- Redis Cluster and Sentinel for high availability
- TLS connections
- Redis ACL support
- Built-in TypeScript declarations
What people use it for
- Caching values in a Node.js backend that already runs Redis
- Storing sorted sets such as leaderboards with zadd and zrange
- Passing messages between Node.js processes with Pub/Sub channels
- Connecting to a Redis Cluster or Sentinel setup for high availability
Frequently asked questions
Is ioredis free to use?
Yes. ioredis is released under the MIT licence, as stated in the project's listing. You can use it in commercial and open-source projects under those terms.
What version of Node.js does ioredis need?
Version 6 of ioredis requires Node.js 20 or newer, according to the README's version table. Older versions of the library support older Node.js releases, so check the table if you maintain an older project.
Does ioredis work with TypeScript?
Yes. The README says ioredis is written in TypeScript and provides official declarations. In a TypeScript project you can also install @types/node as a dev dependency.
Should I use ioredis or node-redis for a new project?
The README says node-redis is the recommended client for new projects, and that ioredis is in best-effort maintenance. Pick ioredis mainly for existing projects that already depend on it.
Why can't ioredis connect to Redis?
The most common cause is that no Redis server is running at the address you gave. By default ioredis connects to localhost:6379, so check that the server is up on that port, or pass the correct host, port or connection string to the constructor.
Does ioredis support Redis Stack features like search and JSON?
The README points to node-redis for Redis Stack features such as search and JSON as a first-class API. It notes that the examples folder includes a Redis Modules example for RedisJSON, but if those features are central to your project, node-redis is the better fit.
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
Use ioredis if you already run Redis with Node.js, maintain a project that depends on it, or need Cluster, Sentinel or Pub/Sub support with TypeScript types. For a new project, the README recommends node-redis instead, and Redis Stack features are better served there.
Install options & downloads