elastic · marciw · Nov 14, 2025 · Nov 14, 2025 · Nov 20, 2025 · Nov 20, 2025
diff --git a/docs/reference/index.md b/docs/reference/index.md
@@ -3,6 +3,9 @@ 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
+applies_to:
+  stack: ga
+  serverless: ga
 ---
 
 # {{es}} Python client [overview]
@@ -11,7 +14,6 @@ This documentation covers the [official Python client for {{es}}](https://github
 
 API reference documentation is provided on [Read the Docs](https://elasticsearch-py.readthedocs.io).
 
-
 The following example shows a simple Python client use case:
 
 ```python
@@ -30,9 +32,6 @@ The following example shows a simple Python client use case:
 {'any': 'data', 'timestamp': '2013-05-12T19:45:31.804229'}
 ```
 
-
-
-
 ## Features [_features]
 
 The client's features include:
@@ -51,11 +50,11 @@ The client also provides a convenient set of [helpers](client-helpers.md) for ta
 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]
+### {{es}} Python DSL [_elasticsearch_python_dsl]
 
 The [Python DSL module](../reference/elasticsearch-dsl.md) offers a convenient and idiomatic way to write and manipulate queries. 
 
-## {{es}} version compatibility [_compatibility]
+## Version compatibility [_compatibility]
 
 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.
 
@@ -66,20 +65,34 @@ Language clients are **forward compatible**: each client version works with equi
 
 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
+## Upgrade to a new major version
 
 :::{important}
 To upgrade to a new major version, first [upgrade {{es}}](docs-content://deploy-manage/upgrade.md), then upgrade the Python client.
 :::
 
-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. 
+As of version 8.0, {{es}} offers a [REST API 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.
+
+### How compatibility mode works
+
+In the Python client, compatibility mode is **always enabled**. You don't need to configure it manually or set an environment variable. The client automatically sends compatibility headers with API requests so that it can communicate with the next major version of {{es}}.
 
 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).
 
-In the Python client, compatibility mode is always enabled. 
+**What to expect in compatibility mode:**
+
+If you're using the Python client in compatibility mode to work with the next major version of {{es}}:
-If you're using the Python client in compatibility mode to work with the next major version of {{es}}:
+If you're taking advantage of the Python client compatibility mode to work with the next major version of {{es}}:
-If you're using the Python client in compatibility mode to work with the next major version of {{es}}:
+If you're taking advantage of the Python client compatibility mode to work with the next major version of {{es}}:
+
+* API calls affected by [breaking changes](../release-notes/breaking-changes.md) might fail or behave differently. 
+* API calls unaffected by breaking changes continue to work as expected.
+* New features from the next major version of {{es}} are not available until you upgrade the client itself.
+
+Although compatibility mode allows your Python client to keep working without intervention, you should upgrade the client when feasible. Even if you don't need the newest {{es}} features, upgrading the client ensures you receive the latest bug fixes and improvements.
 
 :::{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).
-:::
+:::
+
+For guidance on upgrading your {{es}} deployment, refer to the [{{es}} upgrade documentation](docs-content://deploy-manage/upgrade.md) and [upgrade paths](docs-content://deploy-manage/upgrade.md#upgrade-paths).