ioredis tells you to use node-redis for new projects, and 6.x needs Redis 6.2

The project recommends a different client for new work

The second paragraph of the README decides most adoption questions, and it is not marketing.

It says ioredis is a stable project and that maintenance is done on a best-effort basis for relevant issues. The parenthetical matters: contributions will still be evaluated, reviewed and merged when they benefit the project.

Then the sentence that changes the recommendation: for new projects, node-redis is the recommended client library. The README describes it as the open source, MIT licensed Redis JavaScript client redesigned from the ground up and actively maintained, with support for new commands such as hash-field expiration and for future commands, and for the capabilities available in Redis Stack and Redis 8, which it names as search, JSON, time-series and probabilistic data structures.

Both clients live under the same GitHub organisation. This is a successor arrangement rather than a deprecation: the project is not abandoned, contributions are still merged, and the existing release line continued through a v6.0.0 in July 2026.

What it means in practice is that the two situations diverge. For a codebase already on ioredis, the stable-project statement is the reassurance and there is no reason to move. For a new project, the maintainers are telling you to start with node-redis, and the specific reason given is command coverage: hash-field expiration and the Redis Stack and Redis 8 feature set are where ioredis is behind.

If you take that advice, note that it is not a lock-in either. Both clients speak the same protocol, so the migration later is a matter of API surface rather than data.

The version table raises both floors at once

The Versions section is three rows and the middle column is the reason to read it twice:

6.x.x (latest) | main | >= 20 | 6.2 ~ latest
5.x.x | v5 | >= 12 | 2.6.12 ~ latest
4.x.x | v4 | >= 8 | 2.6.12 ~ 7

Read the last column across the rows. The 5.x line supports Redis from 2.6.12. The 6.x line supports Redis from 6.2. The Redis server floor has moved from 2.6.12 to 6.2.

That means upgrading ioredis from 5 to 6 is not a client-only change. It is also a decision about your servers, and one you may not be free to make. If your Redis is managed, you may not control the version, and you may be several major versions behind on a provider that offers no upgrade path. If it is self-hosted, you now own a server upgrade as a prerequisite for a dependency bump.

The Node floor moves too, from 12 to 20. That one is usually easier, though a Node 12 runtime is common enough in older deployments that it deserves a check.

So the practical shape of the upgrade is: confirm the server is on 6.2 or later, confirm the runtime is on 20 or later, and only then take the client.

The README links separate upgrade guides for v5 to v6 and v4 to v5, both on the project wiki, so the details live there rather than in the repository.

Two deprecations are announced in the same document

The basic usage example carries a comment that is more informative than the code around it. It says you can use the named import if your project is TypeScript, that the default import is still supported, but that it will be deprecated in the next major version.

That is the first deprecation, and it is a small one to fix. You change the import line.

The second deprecation is the node-redis recommendation above, which is larger and has no scheduled removal. ioredis is not going away; new feature coverage is simply arriving in the other library.

The combination is worth holding in mind because it tells you the shape of what comes next. The current major is 6, released as v6.0.0 on 2026-07-31 two days after a v6.0.0-beta.1 on 2026-07-29, and v6.1.0-beta.1 followed on 2026-10-12. A default-import removal would be a v7 change.

For an existing codebase this is low urgency and easy to schedule. The practical approach is to fix the import now while you are in the code, so that when the next major does arrive it is not something you discover from a failing build.

The dual callback and promise API is worth pairing with this. The README describes the API as working with both Node callbacks and native promises, which is generous and also means you will encounter both styles in the same codebase depending on age. That is a readability cost rather than a correctness one, but it is the kind of thing that makes a client feel older than its release history suggests.

Fourteen numbered features, and the useful ones are the plumbing

The features list is numbered from zero, which tells you something about how it grew. It opens with full-featured coverage, naming cluster, sentinel, streams, pipelining, Lua scripting, Redis Functions and pub/sub with binary message support.

Then the items that actually distinguish this client from a minimal one: transformation of command arguments and replies, transparent key prefixing, an abstraction over Lua scripting that lets you define custom commands, support for binary data, TLS, an offline queue with ready checking, ES6 types such as Map and Set, GEO commands, Redis ACL, a sophisticated error handling strategy, NAT mapping, and autopipelining.

Read as a group, the differentiating features are the operational ones. Command and reply transformation plus transparent key prefixing is what lets several logical namespaces share one Redis without your code prefixing every key. Offline queue and ready checking is what lets you construct a client before your server is reachable. Redis ACL support is what lets you run with a restricted user rather than the default.

Those are unglamorous and they are the reason to choose this client over a thin wrapper. GEO commands and Map and Set support, by contrast, are table stakes that any mature client has.

Autopipelining is also on the list; check how it works in the documentation before you rely on it, because anything that batches commands on your behalf is worth understanding at the point you adopt it.

100% TypeScript, and TypeScript users still need @types/node

The README states that ioredis is 100% written in TypeScript and that official declarations are provided. Then, two sections later, the install instructions say that in a TypeScript project you may want to add TypeScript declarations for Node.js, with a separate command for the development dependency.

Those two statements are not in conflict. The library ships type declarations for its own API, and what is missing is the Node runtime's own types, which is a separate package covering things like buffers and streams.

It is worth pausing on anyway, because it is the kind of thing that trips people up. A TypeScript project using ioredis pulls two sources of type information: the library's bundled declarations and the ambient Node declarations from a development dependency. If your compiler configuration is strict about which types are visible, a missing @types/node produces errors about Node built-ins rather than anything to do with Redis.

The TypeScript story is otherwise a strength. This is a client whose types ship with the package rather than living in a separately maintained DefinitelyTyped entry, which means the declarations match the released version by construction. The README also lists support for ES6 types such as Map and Set.

Combined with the callback and promise duality noted earlier, the API surface is broad. Reading the hosted API documentation is more necessary here than for a client with a thinner surface, and the README links it for both the Redis and Cluster classes.

semantic-release drives the tags, and a coveralls badge points at the old owner

The badge row at the top of the README carries three build-tool signals and one that has gone stale.

There is a GitHub Actions workflow for releases, a commitizen badge for the cz-cli conventional-commit tool, a semantic-release badge, and a coveralls badge. That coveralls badge points at github.com/luin/ioredis rather than at redis/ioredis, which is the original author's namespace. The repository now lives under the redis organisation, so the badge is a leftover from the project's move.

It is a trivial detail and it is the kind of detail that tells you badges are not maintained alongside the repository. Which matters slightly here, because the release story is otherwise unusually well automated: semantic-release plus commitizen plus a .releaserc.json in the tree plus a dedicated release workflow means version numbers are derived from commit messages rather than chosen by hand.

The recent tags are v6.0.0-beta.1 on 2026-07-29, v6.0.0 on 2026-07-31 and v6.1.0-beta.1 on 2026-10-12.

The version table in the README, not a changelog entry, is the thing to read when you are deciding whether an upgrade is safe.

benchmarks/, test/ and examples/ are all in the tree

The repository inventory is broader than a Redis client strictly needs to be, and it is worth knowing what is there if you are deciding whether to vendor.

Alongside the expected lib/ directory for the library source there are benchmarks/, test/, examples/, docs/, bin/ and resources/. A benchmarks directory in particular is not universal. It means performance work is done in-tree rather than in a separate scratch repository, which is a sign of a project where the performance claim is treated as part of the product.

The API documentation, though, is not in this repository. It is hosted at redis.github.io/ioredis, with separate pages for the Redis and Cluster classes, and the README links the changelog to a file in the tree instead. The upgrade guides live on the wiki.

The remaining files include governance ones: a code of conduct and a security policy. The repository also carries .eslintrc.json, .prettierignore and tsconfig.json, which is the ordinary TypeScript project configuration.

The last push to the repository was on 2026-11-02 and it is not archived, so this is an actively worked-on codebase. The best-effort maintenance statement is about triage of issues, not about the project sitting still.

Editorial conclusion

ioredis suits an existing codebase that already depends on it, where the cost of switching clients is real and the stable-project statement is the reassurance you need. It does not suit a new project, because the maintainers themselves point you at node-redis. Before upgrading from 5.x to 6.x, confirm your Redis servers are already on 6.2 or later, since the client upgrade also raises the Node floor from 12 to 20.

Frequently asked questions

Official sources

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