The Elasticsearch Ruby client is two gems, and version compatibility is one-way

Two libraries, not one, and the split is at the transport

The `elasticsearch` gem is the one you install, and it is a thin composition of two separately versioned libraries.

`elastic-transport` provides the low-level code for connecting to a cluster: the HTTP client, authentication, TLS, retry behaviour and connection pooling. It lives in its own repository at elastic/elastic-transport-ruby and is documented separately on RubyDocs.

`elasticsearch-api` provides the Ruby API surface for the Elasticsearch RESTful API. It lives in a subdirectory of this same repository and is documented as a gem on RubyDocs.

So when you read a bug report or a changelog about this client, knowing which half the problem is in saves time. Connection reuse, timeouts and authentication live in the transport; every endpoint method lives in the API layer.

The repository layout mirrors the split: `elasticsearch/` and `elasticsearch-api/` at the root, with `docs/examples/` holding worked examples and `rake_tasks/`, `scripts/` and a `Rakefile` for the build. `.buildkite/` is the CI system, with a `catalog-info.yaml` at the root indicating the components are declared as internal catalogue entries.

The three-line version of a working client

The complete usage example in the README is this:

require 'elasticsearch'
client = Elasticsearch::Client.new(host: 'https://my-elasticsearch-host.example')
client.ping
client.search(q: 'test')

Install it with:

gem install elasticsearch

`ping` is the connectivity check and `search` takes a query. The keyword arguments pass straight through to the REST API, which is the design: you are calling the server's own parameters, not a curated Ruby abstraction.

The README then links out rather than expands, listing tasks with their own documentation pages: creating an index, indexing a document, getting documents, searching documents, updating documents, deleting documents and deleting an index. Every one is a link into the getting started guide, plus a link to `docs/examples/` in the repository for practical examples.

That is the shape of this repository's README overall. It is a short index that hands off to elastic.co. The information you actually need, including installation options, connecting with credentials and TLS, and the full API reference, is not in this file.

The homepage is https://www.elastic.co/docs/reference/elasticsearch/clients/ruby.

Keep-alive is your responsibility, not the gem's

This paragraph in the README is the single most consequential line for anyone about to put this client in production:

For optimal performance, you should use an HTTP library which supports persistent, keep-alive connections, for example Patron or Typhoeus. Those libraries are not dependencies of the Elasticsearch gems. You have to define the dependency in your own application.

For persistent connections, the README recommends adding Patron or Typhoeus to the application. The vendor is telling you this is on you rather than shipping a default, presumably to avoid pinning a choice of HTTP stack onto every consumer.

So the practical installation order is: add `elasticsearch`, add the HTTP client you want, configure it through the transport layer, and verify that connections are being reused before you benchmark anything. The README does not document the configuration snippet for that, which means it is in the `elastic-transport` documentation rather than here.

Related official libraries are worth knowing about. `elasticsearch-rails` integrates with Ruby models and Rails applications. `elasticsearch-dsl` gives a Ruby API for the Query DSL, which is useful when your queries are large enough that inline hash literals stop being readable. `elasticsearch-extensions` is marked deprecated, so avoid it in new code.

Forward compatible, not backward: read the table before pinning

The compatibility section is where this client differs from most, and the distinction is easy to get wrong.

Language clients are forward compatible. A client supports communicating with greater or equal minor versions of Elasticsearch without breaking. But that does not mean the client automatically supports new features of newer Elasticsearch versions, which only arrives with a new client release. The README's example is explicit: an 8.12 client will not automatically support the new features of 8.13, and the 8.13 client is required for those.

The second half is the part that catches people. Elasticsearch language clients are only backwards compatible with default distributions, and without guarantees made.

The table is short:

| Gem version | Elasticsearch version | Supported | | --- | --- | --- | | 8.x | 8.x | 8.x | | 9.x | 9.x | 9.x | | main | main | none |

So the major versions pair up. A 9.x gem targets 9.x, an 8.x gem targets 8.x. Running an older client against a newer minor server is fine; running a newer client against an older server is outside what the vendor stands behind.

Ruby support follows Ruby's own maintenance policy. The project officially supports all currently maintained versions per the Ruby Maintenance Branches page, so there is no fixed minimum Ruby version to memorise, but it also means your Ruby version eventually falls out of support with a Ruby release rather than a client release.

CI runs a separate workflow per client major

The badges at the top of the README are a maintenance map.

There is a GitHub Actions workflow per supported major, named `8.19.yml`, `9.3.yml` and `9.4.yml`, plus one for `main`. Each is pinned to its own branch, with `9.4.yml` and `main.yml` both carrying a `branch=` parameter. Buildkite runs alongside them at buildkite.com/elastic/elasticsearch-ruby.

That structure tells you how this project is maintained: each client major gets its own test lane against its matching Elasticsearch version, and `main` is tested continuously even when it is not a released version. Fixes are likely to land on `main` and reach the older lines on their own schedule.

Release history is dense. Recent tags are v9.5.0 from 2026-08-04, v9.4.3 and v9.3.4 both from 2026-06-17. The default branch is `main`, the repository is not archived, and the last push was on 2026-10-12.

A CHANGELOG.md at the root, plus CONTRIBUTING.md, CODE_OF_CONDUCT and an AGENTS.md, complete the governance files.

Trying it locally takes one script

To evaluate the client without provisioning anything, the README points at a local startup script:

curl -fsSL https://elastic.co/start-local | sh

That brings up Elasticsearch at http://localhost:9200 and Kibana at http://localhost:5601 using Docker. Those are the two endpoints to point the `host:` option at while you are writing your first query.

The README also links to the downloads page for a full install and to a sign-up link for a free trial of Elastic Cloud, which is the hosted option if you would rather not run anything locally.

Note the tension with the keep-alive advice. A local instance started with this script is fine for development, where connection overhead does not matter and you are not measuring anything. The HTTP client decision belongs to the deployment you will actually run, not to the box you experimented on.

Licensing is Apache 2, with a NOTICE file alongside LICENSE. That covers the client code in this repository; it says nothing about what you may do with Elasticsearch itself, which has its own licensing terms.

Editorial conclusion

Use elasticsearch-ruby if your application is Ruby and you want the vendor-maintained client with API methods generated from the server's own REST surface, which is the main reason to prefer it over a hand-rolled HTTP wrapper. Do not use it if your server is on major 8 and you need 9.x behaviour, since the compatibility table pairs 8.x with 8.x and states backward compatibility carries no guarantee. Before adding the dependency, pick an HTTP client with keep-alive support such as Patron or Typhoeus in your own application, because those libraries are not dependencies of the Elasticsearch gems.

Frequently asked questions

Official sources

1. elastic/elasticsearch-ruby on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases