很多开发者第一次接触 TG 自动化时，都会搜索“python telegram 怎么安装”。实际上，这里说的“安装”通常不是安装 TG 桌面客户端，而是在 Python 项目中安装一个能够连接 TG 的库。结论先行：先明确你要做机器人还是用户客户端，再选库，最后在虚拟环境里用 pip 安装。下面按步骤说明。
一、先分清两种使用场景
TG 官方提供两种主要接入方式：
- Bot API：通过机器人账号工作，适合做频道管理、消息推送、群组助手等。Python 中常用 python-telegram-bot、aiogram 等库。
- MTProto 客户端：以普通用户身份登录，能读取聊天记录、加入群组等，常用 Telethon、Pyrogram 等库。
如果你只是想让程序自动发消息、响应命令，优先选 Bot API 相关库；如果需要模拟真人账号操作，再考虑 MTProto 库。选错方向会导致后续安装和配置走弯路。
二、安装前的环境准备
1. 安装 Python
建议使用 Python 3.9 及以上版本。Windows 用户可从 Python 官网下载安装包，安装时勾选“Add Python to PATH”；macOS 和 Linux 用户可用系统包管理器或 pyenv 安装。安装完成后在终端执行 python --version 确认版本。
2. 创建虚拟环境
强烈建议为每个项目单独创建虚拟环境，避免依赖冲突。在项目目录下执行：
- Windows：
python -m venv venv，然后venv\Scripts\activate - macOS / Linux：
python3 -m venv venv，然后source venv/bin/activate
激活后终端提示符前会出现 (venv) 字样，说明环境已生效。
3. 准备网络与账号
TG 服务在部分网络环境下可能无法直接访问，需要确保你的开发环境能够正常连接 TG 服务器。Bot API 库需要先在 TG 内找 BotFather 创建机器人并获取 token；MTProto 库则需要申请 api_id 和 api_hash。这些凭据不要硬编码在代码里，建议用环境变量管理。
三、安装库的具体命令
进入虚拟环境后，用 pip 安装。以下命令均在终端执行：
| 库名 | 适用场景 | 安装命令 |
|---|---|---|
| python-telegram-bot | Bot API，异步/同步均可 | pip install python-telegram-bot |
| aiogram | Bot API，异步优先 | pip install aiogram |
| Telethon | MTProto 用户客户端 | pip install telethon |
| Pyrogram | MTProto 用户客户端 | pip install pyrogram |
如果下载速度慢，可以临时指定国内镜像源，例如 pip install python-telegram-bot -i https://pypi.tuna.tsinghua.edu.cn/simple。安装完成后执行 pip list 查看是否成功。
四、跑通第一个示例
以 python-telegram-bot 为例，创建一个简单的回声机器人：
- 新建
bot.py，写入基础代码，导入库、定义消息处理函数、启动轮询。 - 将 BotFather 给的 token 放入环境变量，代码中通过
os.environ读取。 - 运行
python bot.py，在 TG 里给机器人发消息，收到同样内容即表示安装和配置成功。
如果你用的是 Telethon，首次运行会要求输入手机号、验证码和两步验证密码，登录成功后会生成 session 文件，后续可复用。
五、注意事项与常见问题
常见报错
- ModuleNotFoundError：多半是虚拟环境没激活，或安装时用了另一个 Python 解释器。确认
pip --version与python --version指向同一环境。 - 连接超时：检查网络能否访问 TG 服务器，必要时配置代理。Bot API 库通常支持通过环境变量设置代理。
- 401 Unauthorized：token 错误或已失效，重新从 BotFather 获取。
- API_ID_INVALID：MTProto 库的 api_id 与 api_hash 不匹配，检查申请信息。
安全提醒
token、api_hash、session 文件都等同于账号凭据，不要上传到公开仓库，也不要发给他人。建议使用环境变量或密钥管理服务。
另外，使用 MTProto 库模拟用户操作时，应遵守 TG 的服务条款，避免高频骚扰、批量加群等行为，否则账号可能被限制。
六、小结
“python telegram 怎么安装”的核心步骤是：明确场景 → 创建虚拟环境 → 选择对应库 → pip 安装 → 配置凭据 → 运行示例。只要环境干净、凭据正确，通常十分钟内就能跑通第一个程序。遇到报错时优先检查虚拟环境和网络，再核对 token 与 api_id，大部分问题都能快速定位。