elasticsearch-py：Elastic 官方 Python 客户端
elasticsearch-py 是 Elasticsearch 的官方 Python 用戶端，提供類型化查詢建構、索引和文件生命週期 API、批次操作、非同步相容性和版本感知客戶端行為。
秒懂
- 它是什麼？
- elastic/elasticsearch-py 提供索引、文档、bulk、异步與 TLS 认证的 Python API，客户端版本與 Elasticsearch minor 版本向前兼容。
- 適合誰用？
- elasticsearch-py 適合已在用 Elasticsearch 並需官方 Python SDK 的团队；不適合期望客户端单独提供與 ES 无关的搜索抽象。升级時先升 Elasticsearch 再升客户端，本地可用 curl -fsSL https://elastic.co/start-local | sh 起 9200/5601 后用 pip 安裝與集群同 major 的 elasticsearch 包做索引與搜索 smoke test。
- 可以商用嗎？
- 可以。Apache-2.0 是寬鬆授權：你可以使用、修改並販售以它為基礎的軟體，只需保留著作權與授權聲明。
- 還在維護嗎？
- 有在維護。儲存庫最近一次提交在 1 天前。
- 用什麼語言寫的？
- 主要是 Python（依據 GitHub 的語言統計）。
以上回答依據專案的 GitHub 資料（最近同步於 2026年9月15日）與我們的分析，不構成法律意見。
開源專案深度解析
官方 Python 客户端與 PyPI elasticsearch 包
elastic/elasticsearch-py README 称 The official Python client for Elasticsearch，主页 ela.st/es-python，Apache-2.0，语言 Python。功能包括 Python 基本类型與 JSON 互转、可設定节点自动发现、持久连接、可插拔负载均衡與失败连接惩罚、TLS 與 HTTP 认证、请求间线程安全、可插拔架构，以及组合 API 的 helper 函数。
安裝见 elastic.co getting-started-python Installation 段；PyPI 包名 elasticsearch，conda-forge 亦有分发。最新 release v9.5.0（2026-08-04）。
PyPI 與 conda-forge 徽章说明双渠道安裝。
stars 4383，Python Apache-2.0，v9.5.0 2026-08-04，ela.st/es-python。conda-forge 與 PyPI 双渠道。
stars 4383，Python Apache-2.0，v9.5.0 2026-08-04，ela.st/es-python。conda-forge 與 PyPI 双渠道。（补充5）
elasticsearch-py 作為官方客户端，API 命名與 Elasticsearch 文档一致。迁移旧專案要同時查 ES deprecations 與 Python 客户端 release note，不能只看 README 功能列表。
elasticsearch7 與 elasticsearch8 包名用于多版本並存，混装時 Python import 路径不同，requirements 应只允许其一除非明确隔离。
客户端升级 checklist 应同時列 elasticsearch-py 版本、ES 集群版本與 start-local 或自有集群的连接串；任何 search 结果异常都要保留 query DSL 與 cluster health 输出。（第 1 节补充）
索引、搜索與文档生命周期 API
README Usage 段链接官方文档章节：Creating an index、Indexing documents、Getting/Searching/Updating/Deleting documents、Deleting an index。具体代码示例不在 README 内，需读 elastic.co Python API 指南。
客户端负责 HTTP 层與类型轉換，索引 mapping、analyzer、集群设置仍在 Elasticsearch 服務端設定。试用時应先确认 ES 版本與客户端 major 对齐再跑 bulk 匯入。
pepy.tech 下载量徽章仅热度参考。
Features：failed connection penalization 失败节点 timeout 前不重试；pluggable load balancing；thread safety。
Features：failed connection penalization 失败节点 timeout 前不重试；pluggable load balancing；thread safety。（补充6）
helper 函数適合 bulk 與 scroll，README 只链接 getting started。团队应為常用 index/search 封装集成测试，而不是复制 elastic.co 示例后不再更新。
Thread safety across requests 在 README Features 列出，高並发應用仍要在應用层限制共享 client 的 mutation。
客户端升级 checklist 应同時列 elasticsearch-py 版本、ES 集群版本與 start-local 或自有集群的连接串；任何 search 结果异常都要保留 query DSL 與 cluster health 输出。（第 2 节补充）
向前兼容：客户端 minor 对齐 ES minor
Compatibility 段：语言客户端 forward compatible，每個客户端版本可與同等及更高 minor 的 Elasticsearch 协同且不破坏。Compatibility does not imply full feature parity：新 ES 特性只在同等客户端版本支持，例如 8.12 客户端完全支持 ES 8.12，可與 8.13 執行但不支持 8.13 新特性；8.13 客户端才完全支持 8.13 特性。
升级 major 時 README TIP：先升级 Elasticsearch，再升级 Python 客户端。
Upgrade major 先升 ES 再升 Python 客户端是 README TIP。
Compatibility：先升 ES 再升客户端；8.12 客户端可跑 8.13 但不支持 8.13 新特性。elasticsearch7/8 旧包名並存。
Compatibility：先升 ES 再升客户端；8.12 客户端可跑 8.13 但不支持 8.13 新特性。elasticsearch7/8 旧包名並存。（补充7）
forward compatible 不等于可随意升 ES minor。新 ES 特性需同等 elasticsearch-py 版本；staging 应列 ES 9.x 與 v9.5.0 客户端对照表。
Failed connection penalization 意味着短暂網路抖动会暂停重试，超時参数要对照 elastic.co Connecting 文档调优。
客户端升级 checklist 应同時列 elasticsearch-py 版本、ES 集群版本與 start-local 或自有集群的连接串；任何 search 结果异常都要保留 query DSL 與 cluster health 输出。（第 3 节补充）
分支对照表與 elasticsearch7/8 包
README 表格：ES main 对应 elasticsearch-py main；ES 9.x 对应 9.x 分支（且 9.x ES 亦可用 8.x 客户端分支）；ES 8.x 对应 8.x 分支。Backward compatible across minor versions 在預設发行版下无保证。
若需並存多版本，旧版也以 elasticsearch7、elasticsearch8 包名發布。选型記錄应写明 pip show elasticsearch 版本與集群 GET / 返回的 version.number。
Helper functions 用于 idiomatic 组合 API 呼叫。
curl elastic.co/start-local 起 9200/5601；Buildkite integration tests；NOTICE+LICENSE 企业分发需保留。
curl elastic.co/start-local 起 9200/5601；Buildkite integration tests；NOTICE+LICENSE 企业分发需保留。（补充8）
backward compatible without guarantees 是免责声明。混合版本或自定义 ES 发行版上，仍要在 staging 跑索引與搜索回归。
CONTRIBUTING.md 描述贡献流程，若向 elasticsearch-py 提交 patch，应跑 CI workflow 與 Buildkite 集成测试。
客户端升级 checklist 应同時列 elasticsearch-py 版本、ES 集群版本與 start-local 或自有集群的连接串；任何 search 结果异常都要保留 query DSL 與 cluster health 输出。（第 4 节补充）
curl start-local 本地 Elasticsearch 與 Kibana
README 提供本地试用命令：curl -fsSL https://elastic.co/start-local | sh，Elasticsearch 在 http://localhost:9200，Kibana 在 http://localhost:5601。更多说明见 Run Elasticsearch locally 文档。
Smoke test 路径：启动本地栈 → pip install 匹配 major 的 elasticsearch → 按文档创建 index → index 一条 doc → search 驗證 hit。CI 链接 GitHub Actions validate workflow 與 Buildkite integration tests。
Thread safety across requests 对多线程写入场景重要。
stars 4383，Python Apache-2.0，v9.5.0 2026-08-04，ela.st/es-python。conda-forge 與 PyPI 双渠道。（补充1）
curl -fsSL https://elastic.co/start-local | sh 適合笔记本起 localhost:9200 與 Kibana 5601，不能当作生产拓扑。記錄 ES 版本号與 pip elasticsearch 包版本一並归档。
conda-forge elasticsearch 包给 Anaconda 使用者提供另一条安裝路径，與 pip 版本号应对齐 v9.5.0。
客户端升级 checklist 应同時列 elasticsearch-py 版本、ES 集群版本與 start-local 或自有集群的连接串；任何 search 结果异常都要保留 query DSL 與 cluster health 输出。（第 5 节补充）
文档站点與 Read the Docs
文档在 elastic.co Python API reference 與 elasticsearch-py.readthedocs.io。CONTRIBUTING.md 描述贡献流程。NOTICE 檔案與 LICENSE 並列。
README 未包含性能基准；bulk 吞吐、连接池大小、retry 策略需查官方 connecting 文档並在目标集群压测。
Features：failed connection penalization 失败节点 timeout 前不重试；pluggable load balancing；thread safety。（补充2）
文档在 elastic.co 與 elasticsearch-py.readthedocs.io。CI 建议对 ES 9.x 與 v9.5.0 跑 smoke test，防止依赖漂移导致连接或 TLS 設定失效。
NOTICE 檔案與 LICENSE 一起在合规审查中阅读，Apache-2.0 专利授权条款对企业分发有影响。
客户端升级 checklist 应同時列 elasticsearch-py 版本、ES 集群版本與 start-local 或自有集群的连接串；任何 search 结果异常都要保留 query DSL 與 cluster health 输出。（第 6 节补充）
v9.5.0 升级核对清单
從 v9.4.x 升 v9.5.0 前：确认 ES 集群已 ≥ 客户端要求的 minor；檢查 breaking changes release note；异步客户端代码路径是否仍用 elasticsearch.AsyncElasticsearch；TLS 证书路径是否在环境变量或 client 参数中更新。
多集群场景記錄每個集群对应的 client 版本，避免 8.x 客户端呼叫 9.x-only API silently 失败。
Compatibility：先升 ES 再升客户端；8.12 客户端可跑 8.13 但不支持 8.13 新特性。elasticsearch7/8 旧包名並存。（补充3）
客户端升级 checklist 应同時列 elasticsearch-py 版本、ES 集群版本與 start-local 或自有集群的连接串；任何 search 结果异常都要保留 query DSL 與 cluster health 输出。（第 7 节补充）
连接层特性與 9.x 分支对照
README Features 强调 Python 基本类型與 JSON 互转、集群节点自动发现、持久连接、可插拔负载均衡策略、基于時间的失败连接惩罚、TLS 與 HTTP 认证、跨请求线程安全、可插拔架构，以及组合 API 的 helper 函数。Installation 指向 elastic.co getting-started-python；Usage 链七篇官方文档涵盖建索引、写入、读取、搜索、更新、删除文档與删索引。Compatibility 表：ES main 对 elasticsearch-py main；ES 9.x 对 9.x 分支且 9.x ES 亦可用 8.x 客户端分支；ES 8.x 对 8.x 分支。Forward compatible 指客户端 minor 对齐 ES minor 可向上兼容更高 minor，但不保证新特性可用；Backward compatible across minor 在預設发行版下无保证。多版本並存可装 elasticsearch7 或 elasticsearch8 旧包名。本地 curl -fsSL https://elastic.co/start-local | sh 起 ES 9200 與 Kibana 5601；文档在 elastic.co 與 Read the Docs 双站；v9.5.0 為当前 release。
curl elastic.co/start-local 起 9200/5601；Buildkite integration tests；NOTICE+LICENSE 企业分发需保留。（补充4）
客户端升级 checklist 应同時列 elasticsearch-py 版本、ES 集群版本與 start-local 或自有集群的连接串；任何 search 结果异常都要保留 query DSL 與 cluster health 输出。（第 8 节补充）
【elastic-elasticsearch-py 补充 1】elastic-elasticsearch-py 文档若有更新，应以 GitHub 預設分支当前 README 為准，並把 tag 或 release 日期写入内部記錄。
【elastic-elasticsearch-py 补充 2】集成 elastic-elasticsearch-py 時，优先复现 README 中带具体命令或环境变量的段落，再扩展到你自己的业务场景。
編輯結論
elasticsearch-py 適合已在用 Elasticsearch 並需官方 Python SDK 的团队；不適合期望客户端单独提供與 ES 无关的搜索抽象。升级時先升 Elasticsearch 再升客户端，本地可用 curl -fsSL https://elastic.co/start-local | sh 起 9200/5601 后用 pip 安裝與集群同 major 的 elasticsearch 包做索引與搜索 smoke test。
社群筆記