.. image:: https://raw.githubusercontent.com/python-telegram-bot/logos/master/logo-text/png/ptb-logo-text_768.png :align: center :target: https://python-telegram-bot.org :alt: python-telegram-bot 标志

.. image:: https://img.shields.io/pypi/v/python-telegram-bot.svg :target: https://pypi.org/project/python-telegram-bot/ :alt: PyPI 包版本

.. image:: https://img.shields.io/pypi/pyversions/python-telegram-bot.svg :target: https://pypi.org/project/python-telegram-bot/ :alt: 支持的 Python 版本

.. image:: https://img.shields.io/badge/Bot%20API-9.5-blue?logo=telegram :target: https://core.telegram.org/bots/api-changelog :alt: 支持的 Bot API 版本

.. image:: https://img.shields.io/pypi/dm/python-telegram-bot :target: https://pypistats.org/packages/python-telegram-bot :alt: PyPI 包月下载量

.. image:: https://app.readthedocs.org/projects/python-telegram-bot/badge/?version=stable :target: https://docs.python-telegram-bot.org/en/stable/ :alt: 文档状态

.. image:: https://img.shields.io/pypi/l/python-telegram-bot.svg :target: https://www.gnu.org/licenses/lgpl-3.0.html :alt: LGPLv3 许可证

.. image:: https://github.com/python-telegram-bot/python-telegram-bot/actions/workflows/unit_tests.yml/badge.svg?branch=master :target: https://github.com/python-telegram-bot/python-telegram-bot/ :alt: Github Actions 工作流

.. image:: https://codecov.io/gh/python-telegram-bot/python-telegram-bot/branch/master/graph/badge.svg :target: https://app.codecov.io/gh/python-telegram-bot/python-telegram-bot :alt: 代码覆盖率

.. image:: https://isitmaintained.com/badge/resolution/python-telegram-bot/python-telegram-bot.svg :target: https://isitmaintained.com/project/python-telegram-bot/python-telegram-bot :alt: 解决问题的中位时间

.. image:: https://api.codacy.com/project/badge/Grade/99d901eaa09b44b4819aec05c330c968 :target: https://app.codacy.com/gh/python-telegram-bot/python-telegram-bot/dashboard :alt: 代码质量：Codacy

.. image:: https://img.shields.io/badge/code%20style-black-000000.svg :target: https://github.com/psf/black :alt: 代码风格：Black

.. image:: https://img.shields.io/badge/Telegram-Channel-blue.svg?logo=telegram :target: https://t.me/pythontelegrambotchannel :alt: Telegram 频道

.. image:: https://img.shields.io/badge/Telegram-Group-blue.svg?logo=telegram :target: https://telegram.me/pythontelegrambotgroup :alt: Telegram 群组

我们为你打造了一个你无法拒绝的封装库。

我们在 Telegram 群组 <https://telegram.me/pythontelegrambotgroup>_ 中拥有一个充满活力的开发者社区，大家互相帮助。快来加入我们吧！

请关注我们的 Telegram 频道 <https://telegram.me/pythontelegrambotchannel>_ ，以获取库的更新和新版本发布信息。

简介

本库为 Telegram Bot API <https://core.telegram.org/bots/api>_ 提供了一个纯 Python 的异步接口。 它兼容 Python 3.10 及以上版本。

除了纯 API 实现之外，本库还提供了一些便捷方法和快捷方式，以及多个高级类，使机器人开发变得简单直接。这些类包含在 telegram.ext 子模块中。

安装_ 本库后，请务必查看关于 使用 PTB_ 的部分。

Telegram API 支持

本库原生支持 Telegram Bot API **9.5** 的所有类型和方法。
此外，尚未原生包含的 Bot API 功能仍可按照 `我们的维基 <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Bot-API-Forward-Compatibility>`_ 中的说明使用。

显著特性
~~~~~~~~

- `完全异步 <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Concurrency>`_
- 方便的快捷方法，例如 `Message.reply_text <https://docs.python-telegram-bot.org/en/stable/telegram.message.html#telegram.Message.reply_text>`_
- `完全标注了静态类型提示 <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Type-Checking>`_
- `可定制且可扩展的接口 <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Architecture>`_
- 与 `webhook <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Webhooks>`_ 和 `轮询 <https://docs.python-telegram-bot.org/en/stable/telegram.ext.application.html#telegram.ext.Application.run_polling>`_ 的无缝集成
- `全面的文档和示例 <#working-with-ptb>`_

安装
----

你可以通过以下命令安装或升级 ``python-telegram-bot``：

.. code:: shell

    $ pip install python-telegram-bot --upgrade

若要安装预发布版本，还需添加 `--pre` 标志 `<https://pip.pypa.io/en/stable/cli/pip_install/#cmdoption-pre>`_。

你也可以从源码安装 ``python-telegram-bot``，不过通常情况下并不需要这样做。

.. code:: shell

    $ git clone https://github.com/python-telegram-bot/python-telegram-bot
    $ cd python-telegram-bot
    $ pip install build
    $ python -m build

你还可以使用你喜欢的包管理工具（如 ``uv``、``hatch``、``poetry`` 等）代替 ``pip``。

验证发布版本
~~~~~~~~~~~~~

为了让你能够确认所下载的发布文件确实是由 ``python-telegram-bot`` 团队提供的，我们采取了以下措施。

自 v21.4 起，所有发布版本均通过 `sigstore <https://www.sigstore.dev>`_ 进行签名。
相应的签名文件已上传至 `GitHub 发布页面`_。
要验证签名，请安装 `sigstore Python 客户端 <https://pypi.org/project/sigstore/>`_，并按照 `从 GitHub Actions 验证签名 <https://github.com/sigstore/sigstore-python?tab=readme-ov-file>`_ 的说明操作。
请将 ``--repository`` 参数设置为值 ``python-telegram-bot/python-telegram-bot``。

较早的发布版本则使用 GPG 密钥进行签名。
签名文件同时上传至 `GitHub 发布页面`_ 和 `PyPI 项目 <https://pypi.org/project/python-telegram-bot/>`_，文件名以 ``.asc`` 结尾。
公钥可在 `这里 <https://github.com/python-telegram-bot/python-telegram-bot/tree/master/public_keys>`_ 找到。
密钥按格式命名：``<first_version>-<last_version>.gpg``。

此外，GitHub 发布页面还包含发布文件的 sha1 哈希值，文件名为 ``.sha1``。

依赖项及其版本

python-telegram-bot 尽量减少对第三方依赖的使用。 然而，对于某些功能来说，使用第三方库比重新实现这些功能更为合理。 由于这些功能是可选的，相应的第三方依赖不会被默认安装。 相反，它们被列为可选依赖。 这样可以避免那些不需要这些可选功能的用户遇到不必要的依赖冲突。

唯一的必需依赖是 httpx >=0.27,<0.29 <https://www.python-httpx.org>_，用于默认的网络后端 telegram.request.HTTPXRequest。

python-telegram-bot 在与其他库结合使用时最为有用。 为了尽量减少依赖冲突，我们在（可选）依赖的版本要求上采取较为宽松的态度。 另一方面，我们又必须确保 python-telegram-bot 的稳定性，因此还是会施加版本限制。 如果您因这些版本限制而遇到依赖冲突，请随时联系我们。

可选依赖 #####################

PTB 可以在安装时包含可选依赖：

• pip install "python-telegram-bot[passport]" 会安装 cryptography>=39.0.1 <https://cryptography.io/en/stable>_ 库。如果您想使用与 Telegram Passport 相关的功能，请使用此选项。
• pip install "python-telegram-bot[socks]" 会安装 httpx[socks] <https://www.python-httpx.org/#dependencies>_。如果您需要通过 Socks5 代理服务器工作，请使用此选项。
• pip install "python-telegram-bot[http2]" 会安装 httpx[http2] <https://www.python-httpx.org/#dependencies>_。如果您想使用 HTTP/2 协议，请使用此选项。
• pip install "python-telegram-bot[rate-limiter]" 会安装 aiolimiter~=1.1,<1.3 <https://aiolimiter.readthedocs.io/en/stable/>_ 库。如果您想使用 telegram.ext.AIORateLimiter，请使用此选项。
• pip install "python-telegram-bot[webhooks]" 会安装 tornado~=6.4 <https://www.tornadoweb.org/en/stable/>_ 库。如果您想使用 telegram.ext.Updater.start_webhook 或 telegram.ext.Application.run_webhook，请使用此选项。
• pip install "python-telegram-bot[callback-data]" 会安装 cachetools>=5.3.3,<6.3.0 <https://cachetools.readthedocs.io/en/latest/>_ 库。如果您想使用 任意回调数据 <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Arbitrary-callback_data>_，请使用此选项。
• pip install "python-telegram-bot[job-queue]" 会安装 APScheduler>=3.10.4,<3.12.0 <https://apscheduler.readthedocs.io/en/3.x/>_ 库。如果您想使用 telegram.ext.JobQueue，请使用此选项。

若要安装多个可选依赖，可以用逗号分隔它们，例如 pip install "python-telegram-bot[socks,webhooks]"。

此外，还提供了两个快捷方式：

• pip install "python-telegram-bot[all]" 会安装所有可选依赖。
• pip install "python-telegram-bot[ext]" 会安装所有与 telegram.ext 相关的可选依赖，即 [rate-limiter, webhooks, callback-data, job-queue]。

使用 PTB

一旦您安装了该库，就可以开始使用它了——让我们马上开始吧！

快速入门

我们的维基中有一篇 `API 简介 <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Introduction-to-the-API>`_，解释了如何通过 ``python-telegram-bot`` 访问纯 Bot API。
此外，`教程：您的第一个机器人 <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Extensions---Your-first-Bot>`_ 提供了关于如何借助 ``telegram.ext`` 模块轻松编写聊天机器人的介绍。

资源
~~~~~~~~~

- `软件包文档 <https://docs.python-telegram-bot.org/>`_ 是 ``python-telegram-bot`` 的技术参考。
  其中包含了所有可用类、模块、方法和参数的描述，以及 `变更日志 <https://docs.python-telegram-bot.org/changelog.html>`_。
- `维基 <https://github.com/python-telegram-bot/python-telegram-bot/wiki/>`_ 包含了许多关于 ``python-telegram-bot`` 各种功能的详细介绍以及其他超出技术文档范围的实用资源。
- 我们的 `示例部分 <https://docs.python-telegram-bot.org/examples.html>`_ 中包含多个示例，展示了 Bot API 和 ``python-telegram-bot`` 的各种特性。
  即使这不是您的学习方式，也请务必看看 ``echobot.py``。它是市面上大多数机器人的事实上的基础代码。
  这些示例的代码已发布到公有领域，您可以直接获取并在此基础上进行开发。
- 当然，`官方 Telegram Bot API 文档 <https://core.telegram.org/bots/api>`_ 也始终值得一读。

寻求帮助

如果上述资源未能解答您的问题，或者让您感到不知所措，您可以通过多种方式获得帮助。

1. 我们有一个活跃的开发者社区，在 Telegram 群组 <https://telegram.me/pythontelegrambotgroup>_ 中互相帮助。欢迎加入！在这里提问通常是获得正确方向指引的最快方式。

2. 您可以通过打开 讨论 <https://github.com/python-telegram-bot/python-telegram-bot/discussions/new>_ 来提问。

3. 您还可以在 Stack Overflow 上使用 python-telegram-bot 标签 <https://stackoverflow.com/questions/tagged/python-telegram-bot>_ 寻求帮助。

并发处理

自 v20.0 起，``python-telegram-bot`` 构建在 Python 的 ``asyncio`` 模块之上。
由于 ``asyncio`` 通常是单线程的，因此 ``python-telegram-bot`` 目前并不追求线程安全。
以下是一些在多线程环境中使用时可能引发问题（例如竞态条件）的 ``python-telegram-bot`` API 部分：

* ``telegram.ext.Application/Updater.update_queue``
* ``telegram.ext.ConversationHandler.check/handle_update``
* ``telegram.ext.CallbackDataCache``
* ``telegram.ext.BasePersistence``
* ``telegram.ext.filters`` 模块中的所有类，这些类允许在运行时添加或移除允许的用户/聊天

自由线程

尽管 python-telegram-bot 已被测试可在 Python 3.14 的自由线程环境下正常工作，但我们并不能保证 PTB 在所有使用场景下都是线程安全的。更多信息请参阅议题 #4873 <https://github.com/python-telegram-bot/python-telegram-bot/issues/4873>_。

贡献

我们欢迎任何形式的贡献。 请查看我们的 贡献指南 <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/.github/CONTRIBUTING.rst>_ 以开始贡献。 您也可以通过 报告 bug 或提出功能请求 <https://github.com/python-telegram-bot/python-telegram-bot/issues/new/choose>_ 来提供帮助。

捐赠

有时我们会收到关于是否接受捐赠以支持开发的询问。 虽然我们非常感谢您的好意，但维护 PTB 只是我们的业余爱好，几乎没有运营成本。因此，我们目前并没有设立任何接收捐赠的渠道。 如果您仍然希望捐赠，恳请您考虑向您选择的其他开源项目或倡议进行捐赠。

许可证

您可以复制、分发和修改本软件，但前提是必须说明所做的修改，并且这些修改必须以 LGPL-3 <https://www.gnu.org/licenses/lgpl-3.0.html>_ 许可证免费授权。 衍生作品（包括修改后的版本或与该库静态链接的任何内容）只能根据 LGPL-3 许可证重新分发，但使用该库的应用程序则无需遵循此许可。

.. _GitHub 发布页面: https://github.com/python-telegram-bot/python-telegram-bot/releases

python-telegram-bot 快速上手指南

python-telegram-bot 是一个纯 Python 编写的异步库，用于轻松开发 Telegram 机器人。它完美支持 Telegram Bot API 9.5+，并提供丰富的高级功能让开发更简单。

环境准备

• 操作系统：Linux, macOS, Windows 均支持。
• Python 版本：需要 Python 3.10 或更高版本。
• 前置依赖：
  • 需预先安装 pip 包管理工具。
  • 核心依赖 httpx 会在安装时自动处理。
  • （可选）如需使用定时任务、Webhook 或 SOCKS 代理等功能，需在安装时指定额外依赖（见安装步骤）。

安装步骤

1. 基础安装

使用 pip 安装最新稳定版：

pip install python-telegram-bot --upgrade

国内开发者提示：如果遇到网络下载缓慢，推荐使用国内镜像源加速：

pip install python-telegram-bot --upgrade -i https://pypi.tuna.tsinghua.edu.cn/simple

2. 安装可选功能

根据需求安装特定功能模块（多个功能可用逗号分隔）：

• 定时任务 (JobQueue):

  pip install "python-telegram-bot[job-queue]"
  

• Webhook 支持:

  pip install "python-telegram-bot[webhooks]"
  

• SOCKS 代理支持:

  pip install "python-telegram-bot[socks]"
  

• 安装所有可选依赖:

  pip install "python-telegram-bot[all]"
  

基本使用

以下是最简单的回声机器人（Echo Bot）示例，它会回复你发送的任何消息。

1. 获取 Token

在 Telegram 中搜索 @BotFather，创建新机器人并获取 API Token。

2. 编写代码

创建文件 bot.py，填入以下内容（将 <YOUR_TOKEN> 替换为你的实际 Token）：

from telegram import Update
from telegram.ext import ApplicationBuilder, ContextTypes, CommandHandler, MessageHandler, filters

async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
    await update.message.reply_text('你好！我是你的第一个 Python 机器人。')

async def echo(update: Update, context: ContextTypes.DEFAULT_TYPE):
    await update.message.reply_text(update.message.text)

if __name__ == '__main__':
    # 替换为你的 Bot Token
    token = '<YOUR_TOKEN>'
    
    application = ApplicationBuilder().token(token).build()
    
    # 注册命令处理器 (/start)
    application.add_handler(CommandHandler("start", start))
    
    # 注册消息处理器 (回复所有非命令文本)
    application.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, echo))
    
    print("机器人正在运行...")
    # 启动轮询模式
    application.run_polling(allowed_updates=Update.ALL_TYPES)

3. 运行机器人

在终端执行：

python bot.py

现在，在 Telegram 中找到你的机器人并发送 /start 或任意消息，即可看到回复。

下一步建议：访问 官方文档 或查看 GitHub Wiki 学习更多高级用法（如内联键盘、回调数据等）。