ioredis: the Redis client for Node.js that now points new projects at node-redis

What ioredis solves for a Node.js service talking to Redis

A Node.js process that talks to Redis needs more than a socket and a command formatter. It needs to survive a dropped connection without losing queued writes, reconnect without restarting the app, and route commands to the right shard when Redis runs in Cluster mode. ioredis is built around those operational concerns rather than around raw command coverage alone.

The README lists the surface it covers: Cluster, Sentinel, Streams, pipelining, Lua scripting, Redis Functions, Pub/Sub including binary messages, TLS, offline queue and ready checking, Redis ACL, NAT mapping and autopipelining. It states support for Redis >= 2.6.12 and full compatibility with Redis 7.x. It also states that the client works with both Node callbacks and native promises, and that it accepts ES6 types such as Map and Set.

The intended user is a backend or platform engineer running Redis in production from Node.js, especially where the deployment is not a single instance. A single-node Redis behind one application server does not need most of this. A service that has to fail over between Sentinel nodes, or shard keys across a cluster, does.

How commands flow: dynamic methods, prefixing and autopipelining

The mechanism is deliberately thin. The README states that all arguments are passed directly to the Redis server, so ioredis supports all Redis commands, and that the call format is redis[SOME_REDIS_COMMAND_IN_LOWERCASE](ARGUMENTS_ARE_JOINED_INTO_COMMAND_STRING). That means redis.set("mykey", "hello", "EX", 10) is equivalent to SET mykey hello EX 10 on the CLI. There is no per-command wrapper to fall out of date when Redis adds one.

Two transforms sit between your call and the wire. Command arguments and replies can be transformed, and key prefixing is transparent, which matters in Cluster mode because the prefix changes how keys hash to slots. The README also lists an abstraction for Lua scripting that lets you define custom commands, so a script is registered once and called like a normal method.

Autopipelining is the other notable behaviour. Commands issued in the same tick are batched onto one round trip instead of each paying its own latency. That is a throughput feature, and it changes the shape of load your Redis server sees: fewer, larger requests rather than a steady stream of small ones. If you are debugging a latency spike, that batching is part of the picture.

Connection setup is equally direct. The README shows that creating a Redis instance opens the connection at the same time, with defaults of 127.0.0.1:6379, and that you can pass a port, a host and port pair, a Unix socket path, or an options object with port, host, username and pass. There is no separate connect call to remember.

Installing ioredis and running a first command

Installation is a single npm package. The README gives this as the install step, and notes that TypeScript projects may want Node.js declarations as a dev dependency.

npm install ioredis
npm install --save-dev @types/node

The basic usage example constructs a client with defaults, writes a key, and reads it back with a promise. The README states that the default connection target is localhost:6379.

const Redis = require("ioredis");

const redis = new Redis();

redis.set("mykey", "value");
redis.get("mykey").then((result) => {
  console.log(result); // Prints "value"
});

Expect the promise to resolve to "OK" for the set, and the get to log value. The README also documents the callback style, where a function passed as the last argument receives (err, result), and notes that the promise form is used when the last argument is not a function. In a TypeScript project the README shows import { Redis } from "ioredis", and notes that the default import still works but will be deprecated in the next major version.

Sorted sets and other data types follow the same pattern. The README's zrange example with WITHSCORES returns a flat array of element and score pairs, in the same order the CLI would print them.

redis.zadd("sortedSet", 1, "one", 2, "dos", 4, "quatro", 3, "three");
redis.zrange("sortedSet", 0, 2, "WITHSCORES").then((elements) => {
  console.log(elements); // ["one", "1", "dos", "2", "three", "3"]
});

The repository ships an examples/ directory with per-type files (string.js, hash.js, list.js, set.js, zset.js, stream.js, ttl.js, module.js) plus a TypeScript example and an Express example, which is where to look for a second use case.

The maintenance signal in ioredis's own README

This is the part that decides the adoption question, and it is unusual to see it stated so plainly by the project itself. The README describes ioredis as a stable project with maintenance done on a best-effort basis for relevant issues, and says contributions will still be evaluated, reviewed and merged when they benefit the project. It then says that for new projects, node-redis is the recommended client library.

That is a support commitment, not a deprecation. The repository is not archived, and the last push was on 2026-09-18, so the code is receiving changes. The v6.0.0 release landed on 2026-07-31, following a beta on 2026-07-29, with v5.11.1 before it on 2026-06-04. So the release cadence is real. What best-effort means is that issue response and feature work follow the maintainers' availability rather than a published schedule, and the README does not commit to one.

The practical consequence: if you file an issue about a new Redis command or a Redis 8 capability, you cannot infer a timeline from the version table. You can infer that the project will keep working, because that is what stable plus best-effort implies.

Where ioredis is the wrong tool

The clearest case is a new service that needs Redis 8 or Redis Stack features. The README states that node-redis supports new commands such as hash-field expiration, plus the capabilities available in Redis Stack and Redis 8: search, JSON, time-series and probabilistic data structures. The ioredis README does not claim those. If your design depends on them, choosing ioredis means either waiting or reaching past the client.

Version support is the second boundary, and it is easy to get wrong because it is per release line. The README's table gives 6.x.x on the main branch requiring Node.js >= 20 and Redis 6.2 through latest; 5.x.x on the v5 branch requiring Node.js >= 12 and Redis 2.6.12 through latest; and 4.x.x on v4 requiring Node.js >= 8 and Redis 2.6.12 through 7. A team on an older Node.js runtime cannot simply take the newest ioredis, and the README points v5 users at a separate upgrade wiki page for the v5 to v6 move.

Cluster key prefixing is the third sharp edge. Because prefixing is transparent, a key you think you are writing becomes a different key on the server. That is the intended behaviour and it is documented, but it interacts with Cluster slot assignment, and it is the kind of thing that only shows up when you inspect keys directly or move between environments with different options.

The README does not document rollback for a failed upgrade, and it does not publish a support window or end-of-life date for any branch. If your organisation requires a vendor-backed support commitment, that absence matters more than any feature list.

ioredis vs node-redis: the actual difference

Both are MIT-licensed Redis clients for JavaScript, and both are under the redis organisation on GitHub. The difference is where each one is pointed.

node-redis is described in the ioredis README as the open-source Redis JavaScript client library redesigned from the ground up and actively maintained, with support for new and future commands and the Redis Stack and Redis 8 capabilities. That is the project the README steers new work toward.

ioredis is the older, broader-surface client. Its differentiators, per its own feature list, are the callback plus promise duality, transparent key prefixing, the Lua scripting abstraction for defining custom commands, offline queue and ready checking, NAT mapping, and autopipelining. Those are ergonomics and connection-handling choices rather than protocol differences. If your codebase is written against callbacks, or you rely on the custom-command abstraction, moving to node-redis is a rewrite of call sites, not a dependency swap.

If you are comparing against a hosted Redis-compatible service, the relevant question is not the client's feature list but whether that service supports the commands and cluster topology you use. What is documented here covers the client, not any hosted product.

Licence, upgrade cost and what to check before you commit

The licence is MIT, as stated in the repository metadata and in package.json. That permits commercial use and modification under the usual MIT terms. This is a description of the licence identifier, not legal advice; if your organisation has a policy on dependency licences, run it through that process. The package also declares an Open Collective funding URL, which is a donation channel, not a commercial support contract.

Upgrade cost depends on which line you are on. Moving from v5 to v6 changes the required Node.js floor from >= 12 to >= 20, and the README links a dedicated wiki page for that migration. Moving from v4 to v5 has its own wiki page. Both are documented as separate guides rather than folded into the README, which suggests non-trivial changes in each. The package's prepublishOnly script runs a version generator and then the TypeScript build, and the published files field is limited to built/, so consumers get compiled output and declarations, not the TypeScript sources.

For local verification, the repository defines docker:setup and docker:teardown scripts that bring up and tear down the test stack from test/docker-compose.yml, with test:js, test:cluster and test:tsd as separate suites. If you want to check whether a behaviour you depend on is covered, those script names tell you where the coverage lives.

What to verify first, concretely: your Node.js version against the table row for the ioredis line you intend to install, your Redis server version against the same row, and whether any key prefix option in your current config will change key names under Cluster.

Editorial conclusion

Adopt ioredis if you already run it, or if you need its Cluster and Sentinel handling and its callback plus promise API in one client. Do not adopt it for a greenfield service: the README itself says node-redis is the recommended client library for new projects, and ioredis is described as maintained on a best-effort basis. Before committing, check the Node.js and Redis version row for your release line, run the v5 to v6 upgrade notes against your key prefixing and Lua usage, and confirm which Redis 8 features you need, because the README credits node-redis, not ioredis, with hash-field expiration and the Redis Stack capabilities.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. redis/ioredis on GitHub
5. Releases