Skip to content

[DOCS] Clarify upgrades and edit generally #3138

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
+30 −27
Open

[DOCS] Clarify upgrades and edit generally #3138

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
8093f5d
Revise upgrade section; do a general edit
marciw Oct 29, 2025
f8925df
fix mis-paste
marciw Oct 29, 2025
f4edf60
More edits
marciw Oct 30, 2025
de9b5e2
Review comments + more cleanup
marciw Oct 31, 2025
07a3a7d
Merge branch 'main' into mw-compatibility
marciw Nov 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 30 additions & 27 deletions docs/reference/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,17 +1,18 @@
---
navigation_title: "Python"
mapped_pages:
- https://www.elastic.co/guide/en/elasticsearch/client/python-api/current/index.html
- https://www.elastic.co/guide/en/elasticsearch/client/python-api/current/overview.html
---

# Python [overview]
# {{es}} Python client [overview]

This is the official Python client for {{es}}. Its goal is to provide common ground for all {{es}}-related code in Python. For this reason, the client is designed to be unopinionated and extendable. API reference documentation for this client is available on [Read the Docs](https://elasticsearch-py.readthedocs.io).
This documentation covers the [official Python client for {{es}}](https://github.com/elastic/elasticsearch-py). The goal of the Python client is to provide common ground for all {{es}}-related code in Python. The client is designed to be unopinionated and extendable.

API reference documentation is provided on [Read the Docs](https://elasticsearch-py.readthedocs.io).

## Example use [_example_use]

Simple use-case:
The following example shows a simple Python client use case:

```python
>>> from datetime import datetime
Expand All @@ -29,14 +30,12 @@ Simple use-case:
{'any': 'data', 'timestamp': '2013-05-12T19:45:31.804229'}
```

::::{tip}
For an elaborate example of how to ingest data into Elastic Cloud, refer to [this page](docs-content://manage-data/ingest/ingesting-data-from-applications/ingest-data-with-python-on-elasticsearch-service.md).
::::



## Features [_features]

The client’s features include:
The client's features include:

* Translating basic Python data types to and from JSON
* Configurable automatic discovery of cluster nodes
Expand All @@ -46,37 +45,41 @@ The client’s features include:
* Thread safety
* Pluggable architecture

The client also contains a convenient set of [helpers](client-helpers.md) for some of the more engaging tasks like bulk indexing and reindexing.
The client also provides a convenient set of [helpers](client-helpers.md) for tasks like bulk indexing and reindexing.

::::{tip}
To get started, try this walkthrough: [Ingest data with Python](docs-content://manage-data/ingest/ingesting-data-from-applications/ingest-data-with-python-on-elasticsearch-service.md)
::::

## Elasticsearch Python DSL [_elasticsearch_python_dsl]

For a higher level access with more limited scope, have a look at the DSL module, which provides a more convenient and idiomatic way to write and manipulate queries.
### Elasticsearch Python DSL [_elasticsearch_python_dsl]

The [Python DSL module](../reference/elasticsearch-dsl.md) offers a convenient and idiomatic way to write and manipulate queries.

## Compatibility [_compatibility]
## {{es}} version compatibility [_compatibility]

Language clients are _forward compatible:_ each client version works with equivalent and later minor versions of {{es}} without breaking.
Language clients are **forward compatible**: each client version works with equivalent and later minor versions of the **same or next major** version of {{es}}. For full compatibility, the client and {{es}} minor versions should match.

Compatibility does not imply full feature parity. New {{es}} features are supported only in equivalent client versions. For example, an 8.12 client fully supports {{es}} 8.12 features and works with 8.13 without breaking; however, it does not support new {{es}} 8.13 features. An 8.13 client fully supports {{es}} 8.13 features.
| Client version | {{es}} `8.x` | {{es}} `9.x` | {{es}} `10.x` |
|----------------|---------------------------------|---------------------------------|----------------------------------|
| 9.x client | ❌ Not compatible with {{es}} 8.x | ✅ Compatible with {{es}} 9.x | ✅ Compatible with {{es}} 10.x |
| 8.x client | ✅ Compatible with {{es}} 8.x | ✅ Compatible with {{es}} 9.x | ❌ Not compatible with {{es}} 10.x |

| Elasticsearch version | elasticsearch-py branch |
| --- | --- |
| main | main |
| 9.x | 9.x |
| 9.x | 8.x |
| 8.x | 8.x |
Compatibility does not imply feature parity. New {{es}} features are supported only in equivalent client versions. For example, an 8.12 client fully supports {{es}} 8.12 features and works with 8.13 without breaking, but it does not support new {{es}} 8.13 features. An 8.13 client fully supports {{es}} 8.13 features.

{{es}} language clients are also _backward compatible_ across minor versions — with default distributions and without guarantees.
{{es}} language clients are also **backward compatible** across minor versions, with default distributions and without guarantees.

### Major version upgrades

:::{tip}
To upgrade to a new major version, first upgrade {{es}}, then upgrade the Python {{es}} client.
:::{important}
To upgrade to a new major version, first [upgrade {{es}}](docs-content://deploy-manage/upgrade.md), then upgrade the Python client.
:::

Since version 8.0, the {{es}} server supports a compatibility mode that allows smoother upgrade experiences. In a nutshell, this makes it possible to upgrade the {{es}} server to the next major version, while continuing to use the same client. This gives more room to coordinate the upgrade of your codebase to the next major version.
As of version 8.0, {{es}} offers a [compatibility mode](elasticsearch://reference/elasticsearch/rest-apis/compatibility.md) for smoother upgrades. In compatibility mode, you can upgrade your {{es}} cluster to the next major version while continuing to use your existing client during the transition.

For example, to upgrade a system that uses {{es}} 8.x you can upgrade the {{es}} server to 9.x first, and the 8.x Python {{es}} client will continue to work (aside from any breaking changes, which should be listed in the server release notes). You can continue using the 8.x client during the server migration, and only upgrade it once the server migration is complete. The process is described in detail in the [REST API compatibility workflow](https://www.elastic.co/docs/reference/elasticsearch/rest-apis/compatibility#_rest_api_compatibility_workflow) section of the {{es}} documentation.
For example, if you're upgrading {{es}} from 8.x to 9.x, you can continue to use the 8.x Python client during and after the {{es}} server upgrade, with the exception of [breaking changes](../release-notes/breaking-changes.md).

If you need to work with multiple client versions, note that older versions are also released with the `elasticsearch8` and `elasticsearch9` package names so that they can be installed together.
In the Python client, compatibility mode is always enabled.

:::{tip}
To support working with multiple client versions, the Python client is also released under the package names `elasticsearch8` and `elasticsearch9` (to prevent name collisions).
:::