A telegram downloader on windows and linux platform based on Python.
Note
由于本项目提供的Linux版本可能对较早版本的Linux系统兼容性较差。
若无法运行的Linux用户请阅读:"3.0.在生产环境中运行(对于Linux用户)"或"6.0.通过Docker运行"。
如果你遇到任何问题，请先仔细阅读:"常见问题及解决方案汇总"。
没有找到解决方案再进群或私聊提问。
本项目以MIT协议开源发布，本项目及依赖本项目发布的软件均为免费非盈利性质。仅限于合法、合规的用途。严禁使用本软件从事任何违反法律法规、侵犯他人合法权益或干扰平台正常运营的行为。
所有使用本软件的行为及其后果均由使用者自行承担全部法律责任，开发者不对任何使用行为及其后果负责。
本项目按“原样”提供，不附带任何明示或暗示的保证。
| 作者 | Gentlesprite |
|---|---|
| B站视频教程 | 点击观看 |
| Telegram交流群 | 点击加入 |
| 支持作者 | 点击跳转 |
| 平台 | 下载地址 | 备注 |
|---|---|---|
| 蓝奏云 | 点击跳转 | 密码:ceze |
| Github | 点击跳转 | – |
| Gitcode | 点击跳转 | – |
| Gitee | 点击跳转 | 仅发布源码 |
| Telegram交流群 | 点击加入 | 群文件 |
点击展开
-
对于Windows11用户，
Windows Terminal默认已经安装好，可跳过下载的步骤，直接前往第3步。(将Windows Terminal设为默认终端) -
对于Windows10用户，推荐使用
Windows Terminal作为默认终端，仅作为推荐安装，无论安装与否不会影响本软件的使用，Windows Terminal能提供更出色的显示、交互、体验效果，以及避免出现文字显示乱码。Windows Terminal下载地址如下表:平台 下载地址 微软商店 点击跳转 Github 点击跳转 -
下载完成完成后
win+r输入wt回车打开，然后将Windows Terminal设为默认终端再启动软件，教程如下:
-
填写自己绑定
Telegram电报的手机号注意手机号格式先要+地区再写入电话号码例如+12223334455，+1为地区，222333445为你绑定Telegram的手机号，填写后点击Next。
-
打开你的
Telegram客户端，此时会收到来自Telegram账号的消息，将上面的验证码填入Confirmation code框中，然后点击Sign in。
-
点击
API development tools按照提示填入即可。
-
申请成功会得到一个
api_hash和api_id保存下载，切记不要泄露给任何人！
Note
如果配置了机器人，只要保持软件运行，就能实现多端发送下载命令并且随时进行下载。
故可以将软件部署在服务器上，无论是Windows还是Linux平台。
Windows平台可直接使用releases里发布的二进制文件放在服务器运行。
Linux平台的部署教程请阅读:"3.0.在生产环境中运行(对于Linux用户)"。
点击展开
-
打开后会提示"要打开 Telegram Desktop 吗?"此时点击"打开Telegram Desktop"如下图所示：
如果没有这个弹窗，说明电脑没有安装Telegram客户端，安装后再重试即可。
-
点击开始，如下图所示：
-
然后在当前聊天框中输入
/newbot后回车，如下图所示：
它会回复你
"Alright, a new bot. How are we going to call it? Please choose a name for your bot."意思是给机器人取一个名字，如下图所示：
-
这个名字是显示名称 (display name)，并不是唯一识别码，随便设置一下即可，之后可以通过
/setname命令进行修改。
-
接着设置机器人的唯一名称。字符串必须 以
bot结尾，比如HelloWorld_bot或HelloWorldbot都是合法的。如果设置的名字已经被占用需要重新设置。如设置成了trmd_bot但是这个名字已经有人使用了，此时会提示"Sorry, this username is already taken. Please try something different."意思是已经被使用了，需要拟定一个不重复的，如下图所示：
如果结果如上图所示，则就代表名字重复了，需要重新拟定一个。
-
直到提示你
"Done! Congratulations on your new bot. . ."如下图所示：
如果结果如上图所示，则代表
bot_token申请成功了，箭头指的红框处就是你所申请的bot_token，切记不要泄露给任何人！
-
申请完成后，在软件配置时询问"是否启用「机器人」(需要提供bot_token)? - 「y|n」(默认n)"选择
y代表需要使用，如下图所示：
然后在上图箭头所指处填入"2.2.1.申请教程"第7步申请的
bot_token后回车，即可配置完成。 -
在一切配置完成，软件启动成功后等待提示"「机器人」启动成功。"，就代表机器人可以使用了，如下图所示：
-
在
Telegram客户端中找到与BotFather的对话框，找到"2.2.1.申请教程"第7步对话的位置(或者用你自己的方式找到你的机器人的对话框)，如下图所示：
然后在上图箭头所指处即可跳转到机器人对话框。
-
点击开始，如下图所示：
不出意外，会收到一条来自机器人发送的消息，如下图所示：
如果没收到尝试尝试给机器人发送任意命令。
-
目前机器人支持的命令用法及解释如下表所示：
命令 用法 解释 /help向机器人发送发送 /help即可。展示可用命令。 /download/download 链接1 链接2 链接3 链接n或/download 频道链接 1 100分配新的下载任务，两种方式可选(指定链接下载和范围下载，具体使用方法请见下方说明)。 /table向机器人发送 /table即可。在终端输出当前下载情况的统计信息。 /forward/forward https://t.me/A https://t.me/B 1 100将频道A的消息转发至频道B，其中 1代表起始ID，100代表截止ID。/exit向机器人发送 /exit即可。退出软件。 /listen_download/listen_download https://t.me/A https://t.me/B https://t.me/n实时监听频道A、频道B和频道n的最新消息(视频和图片)进行下载。 /listen_forward/listen_forward https://t.me/A https://t.me/B实时监听频道A的最新消息(任意消息)转发至频道B。但当频道A为私密频道时候无法转发。 /listen_info向机器人发送 /listen_info即可。查看当前已经创建的监听信息。 /upload/upload本地文件目标频道上传本地的文件到指定频道。 /upload_r/upload_r 本地文件夹 目标频道递归上传文件夹(包含子文件夹)到指定频道。 /download_chat/download_chat 频道链接下载指定频道并支持通过内联键盘自定义内容过滤。 其他功能:
- （
≥v1.8.7）转发视频、图片、音频、语音、GIF、文档类型的消息给机器人，即可自动下载。- 此项功能不受用户自定义下载类型限制，确保文件即时获取。
- 转发的消息将按新消息处理，每次均生成独立文件命名。暂不支持重复文件识别，请妥善管理多次转发的相同内容。
- 此功能仅用于便利用户日常使用，对于无法被转发、下载的消息，请根据实际需求使用对应的命令。
- （
-
/help命令使用教程，如下图所示：
-
点击菜单可以显示机器人可用的命令，如下图所示：
-
/download命令使用教程，如下图所示：⚠️ 注意：
自版本≥v1.6.3起：
已全面支持下载时的断点续传功能（支持所有上传场景），增强了在较差网络环境下的传输稳定性与可靠性。-
方式一：
- 只要发送了正确的下载命令，终端就会创建对应的下载任务，如下图所示：
-
方式二：
-
该功能为版本
≥v1.5.1的新增功能，用于对于单一链接的范围下载，并且该方式要求指定频道链接、起始ID与结束ID：# 语法格式如下： /download 频道链接 起始ID 结束ID # 举例： /download https://t.me/test 1 500 # 代表下载https://t.me/test从消息ID=1到结束ID=500的媒体。
-
-
-
/table命令使用教程：需要注意的是，这个表格是实时的状态，并不是最终下载完成的结果，每一次使用它都会随着当前的下载记录而更新。
链接统计表的使用，如下图所示:
注意：由于早期代码设计缺陷，链接统计表为后续支持的功能：
-
链接统计表仅会统计所有支持的类型，并不会只统计用户当前所选择的类型。
-
链接统计表对于评论区媒体的统计，会出现总数统计错误的问题，体现在总数为
1，小于当前的下载数，完成率>>100%的问题(该问题已在≥v1.5.9修复)。 -
当用户未选择下载所有支持的类型时，在用户所选择的类型下载完成后(或使用机器人发送链接统计表)，尽管所有用户指定类型的文件已经下载完成，当链接统计表显示
完成率不为100%时，代表该链接还存在其他用户未指定的文件类型，但实际用户所指定的类型已经下载完成了，是正常情况。 -
版本
≥v1.6.5起已支持导出表格功能，通过该命令可在运行时控制是否在退出后导出指定类型的表格。
计数统计表的使用，如下图所示:
-
-
/forward命令使用教程：⚠️ 注意：
消息能否转发，在于频道是否开启了限制保存内容功能。
如果无法转发，机器人会在聊天框提供一个下载按钮与下载后上传按钮(≥v1.6.7)。
自版本≥v1.6.9起：
/forward将支持过滤转发类型。
可通过[帮助页面]->[设置]->[转发设置]进行修改。
自版本≥v1.7.5起：
为确保"受限转发"功能顺利完成，在下载后上传过程中，创建下载任务时将忽略配置文件中设置的下载类型限制，此时（指"受限转发"情况）/forward命令无法按照[转发设置]过滤类型。
自版本≥v1.8.5起：
为确保"受限转发"功能顺利完成，在下载后上传过程中，创建下载任务时将忽略该链接是否被重复添加的判定。
-
转发消息语法：
/forward 频道A 频道B 起始ID 结束ID
-
实例：
- 该实例代表转发
https://t.me/test频道中从消息ID=1到结束ID=500的消息到https://t.me/test2频道。
/forward https://t.me/test https://t.me/test2 1 500
- 该实例代表转发
-
转发至个人收藏夹（任选一种命令即可）：
-
方式1，使用me或self指向个人收藏夹（任选一种命令即可）：
/forward https://t.me/test me 1 500
/forward https://t.me/test self 1 500
-
方式2，使用
https://t.me/用户名：- 用户名即指个人账户信息里@后面那一串，需用户提前手动自己设置，否则无法使用该方式。
- 例如通过查询个人信息，得知当前设置的用户名为
@developer，此时指向个人的链接即为https://t.me/developer。
/forward https://t.me/test https://t.me/developer 1 500
-
无论使用方式1或方式2，都代表转发
https://t.me/test频道 中从消息ID=1到结束ID=500的消息到个人收藏夹。
-
-
转发个人收藏夹的内容至任意频道：
-
方式1：
/forward me https://t.me/test 1 500
-
方式2：
/forward https://t.me/developer me 1 500
-
无论使用方式1或方式2，都代表转发个人收藏夹中从
消息ID=1到结束ID=500的消息到https://t.me/test频道。
-
/exit命令使用教程，如下图所示：
/listen_download命令使用教程：
-
/listen_download监听下载用于，实时监听该链接的最新消息进行下载。- 在用户发送了正确的监听命令后，会收到机器人的成功提示。
- 当被监听的频道有可下载的内容时，就会自动发送命令下载。
-
/listen_download https://t.me/A
-
/listen_download https://t.me/A
-
/listen_download https://t.me/A https://t.me/B https://t.me/n
-
/listen_download https://t.me/A https://t.me/B https://t.me/n
-
/listen_forward命令使用教程：⚠️ 注意：
自版本≥v1.6.7起：
当检测到"受限转发"时，自动采用"下载后上传"的方式(默认开启)。
当下载并完成上传后，可选择是否删除本地文件(默认关闭)。
并且可通过[帮助页面]->[设置]->[上传设置]进行修改。
自版本≥v1.6.9起：
/listen_forward将支持过滤转发类型。
可通过[帮助页面]->[设置]->[转发设置]进行修改。
自版本≥v1.7.5起：
为确保"受限转发"功能顺利完成，在下载后上传过程中，创建下载任务时将忽略配置文件中设置的下载类型限制。
自版本≥v1.8.5起：
为确保"受限转发"功能顺利完成，在下载后上传过程中，创建下载任务时将忽略该链接是否被重复添加的判定。
-
/listen_forward监听转发用于，实时监听该链接的最新消息。- 与
/forward命令一样，消息能否转发，在于频道是否开启了限制保存内容功能。 - 但在
≥v1.6.7起可以通过下载再上传的方式进行"转发"。 - 在用户发送了正确的监听命令后，会收到机器人的成功提示。
- 当被监听的频道有任何新内容时，就会自动转发至用户所指定的频道。
- 与
-
- 频道独占原则：
- 每个频道同一时间只能激活一种监听模式（下载或转发）。
- 对于
/listen_forward命令，"同一频道"特指被监听的源频道。 - 转发目标频道不受此限制，仍可通过
/listen_download创建下载任务。
- 操作限制：
- 当
频道A正在监听转发频道B时：- 可以同时在
频道B设置监听下载。 - 但
频道B的监听下载，不会响应来自频道A的监听转发。
- 可以同时在
- 当
- 监听切换流程：
- 必须先通过同一命令(注册监听时的命令)来取消现有监听。
- 然后才能创建新的监听事件。
- 频道独占原则：
-
/listen_forward https://t.me/A https://t.me/B
-
/listen_forward https://t.me/A https://t.me/B
/listen_info命令使用教程：
-
/listen_info用于查看当前已经创建的监听信息，直接发送即可：/listen_info
/upload命令使用教程：⚠️ 注意：
自版本≥v1.7.9起：
已全面支持上传时的断点续传功能（支持所有上传场景），增强了在较差网络环境下的传输稳定性与可靠性。
自版本≥v1.8.4起：
/upload命令支持me、self作为目标频道的参数（me、self作为目标频道参时，代表指向个人收藏夹Saved Messages）
-
/upload用于上传本地的文件到指定频道。- 支持上传文件夹（当指定路径为文件夹时并且版本需≥v1.7.1）。
- 当指定的路径为文件夹时，将会上传指定文件夹下所有的文件。
-
上传文件语法：
/upload 本地文件(夹) 目标频道
Telegram对上传的单个文件大小设有明确限制：- 普通用户：单个文件最大上传大小为
2000 MiB（约 2 GB） - 会员用户（Telegram Premium）：单个文件最大上传大小为
4000 MiB（约 4 GB）
/upload C:\files\video.mp4 https://t.me/test
/upload C:\files https://t.me/test/upload /home/username/files/video.mp4 https://t.me/test/upload /home/username/files https://t.me/test - 普通用户：单个文件最大上传大小为
-
/upload_r命令使用教程：⚠️ 注意：
自版本≥v1.8.4起：
/upload_r命令支持me、self作为目标频道的参数（me、self作为目标频道参时，代表指向个人收藏夹Saved Messages）。-
/upload_r命令是/upload命令的扩展版本，专为批量文件上传场景设计，支持递归处理目录结构，与/upload不同的是：-
/upload_r命令接收文件夹路径作为其第二个参数，自动遍历该目录及其所有子目录中的文件。/uploadr C:\files https://t.me/test -
当第二个参数为文件路径时，自动切换为
/upload的单文件上传模式。/uploadr C:\files\video.mp4 https://t.me/test
/upload C:\files\video.mp4 https://t.me/test
以上两个命令在功能上完全等效，系统会自动识别文件类型并采用相应的上传策略。
-
-
-
/download_chat命令使用教程：
-
/download_chat下载指定频道。- 与
/download不同的是：/download_chat支持通过机器人发送的内联键盘进行自定义内容过滤。 - 该命令支持下载无法复制具体请求链接的对话。
- 使用该命令后，需要通过操作机器人回复中的内联键盘，来设置过滤器、执行任务或取消任务。
- 需要注意的是，在上一个
/download_chat命令任务未执行或取消前，无法发起新的/download_chat命令来创建下载任务。 - 自版本
≥v1.7.5起，/download_chat命令创建的下载任务过滤条件将完全遵循用户在内联键盘中的设置，意味着该命令不会遵循配置文件中的任何规则（例如配置文件中的下载文件类型设置）。
- 与
-
目前支持的过滤方式：
过滤方式 默认值 日期范围 第一条消息的发送日期～最后的一条消息的发生日期文件类型 视频、图片、音频、语音、GIF、文档匹配关键词 – 包含评论区 关 -
下载指定频道语法：
/download_chat 频道链接
-
发送命令后，可根据个人需求设置过滤器（可选）。
-
在设置完成后，必须手动点击"执行任务"或"取消任务"以继续或终止流程，否则该命令将始终处于等待状态，并阻塞新的
/download_chat命令。
-
-
下载用户与机器人的对话媒体:
用户与机器人的对话无法复制具体的请求链接，因此该方法用于解决某些用户与机器人对话中禁止用户进行转发、下载的情况。
-
首先要获取机器人用户名称，在聊天对话框中点击机器人名称查看其用户名，此处假设机器人名称为
@developer_bot。 -
拼接机器人的请求链接为
https://t.me/developer_bot。/download_chat https://t.me/developer_bot
-
-
下载个人收藏夹（任选一种命令即可）:
-
方式1（任选一种命令即可）：
/download_chat me
/download_chat self
-
方式2：
- 首先要获取用户名称，此处假设用户名已设定，个人信息中查看用户名为
@developer。 - 拼接个人收藏夹的请求链接为
https://t.me/developer。
/download_chat https://t.me/developer
- 首先要获取用户名称，此处假设用户名已设定，个人信息中查看用户名为
-
-
自版本
≥v1.8.8起，/download_chat命令新增通过匹配关键词下载，匹配关键词说明：-
该命令会根据消息的
text（文本）和caption（标题）信息，筛选并下载包含所设置关键词的相关对话内容。 -
在使用该命令后点击[
🔑设置匹配关键词]此时，机器人将进入接收关键词模式。 -
关键词可以为一个或多个，当关键词为多个时，以空格分隔，例如：
我的最爱学习 资料 健康 营养 -
用户再次发送已添加的关键词时，机器人会提供一个[
⌨️内联键盘]按钮用于[🗑️移除]或[👁️🗨️忽略]该关键词。 -
同一时段内发送多个相同的已添加关键词，只会对第一个触发移除选项，后续重复内容不会重复触发。
-
在[
🔑设置匹配关键词]界面：- 点击[
✅确认关键词]时，将会添加所有设置的关键词。 - 点击[
❌取消]时，将会清空所有设置的关键词。 - 点击[
🔙返回]时，不做任何操作，仅返回至主页面。
- 点击[
-
-
包括评论区设置说明：
- 评论区开关：
- 默认为关闭状态。
- 开启时，按钮状态为[
✅包含评论区]，匹配到的消息，存在评论区模块时，进一步匹配评论区。 - 关闭时，按钮状态为[
❌包含评论区]，匹配到的消息，存在评论区模块时，忽略评论区内容。
- 评论区功能适用性：
- 平台部分频道在消息下方设有评论区模块，该功能为可选扩展项。用户需基于个人实际需求，自行判断是否需同步获取评论区内容。 评论区匹配与过滤规则：
- 仅匹配并处理已成功提取的对应消息下方的评论区内容。
- 评论区的过滤条件仅遵循本次任务中用户指定的
媒体类型作为过滤条件，其余过滤条件将被忽略（例如日期）。
- 任务处理时效性：
- 开启评论区获取功能后，需对所匹配到的消息的评论区进行读取，消息过多时，任务创建至完成的时间可能相应延长，需耐心等待。
- 评论区开关：
Note
用户配置文件通常无需自行配置，此处旨在介绍全局配置文件中各参数的含义。
用户配置文件会在软件启动时自动在软件目录下生成config.yaml文件，并详细地引导用户配置参数。
手动编辑config.yaml对配置进行修改时，请仔细阅读下面内容理解各参数含义。
需注意配置文件使用的引号、冒号均为半角，冒号后需有一个空格。
api_hash: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # 申请的api_hash。
api_id: 'xxxxxxxx' # 申请的api_id。
# bot_token（选填）如果不填，就不能使用机器人功能。可前往https://t.me/BotFather免费申请。
bot_token: 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
download_type: # 需要下载的类型。支持的参数:video,photo,document,audio,voice,animation。
- video # 视频。
- photo # 图片。
- document # 文档。
- audio # 音频。
- voice # 语音。
- animation # GIF。
- video_note # 视频笔记。
is_shutdown: true # 下载完成后是否自动关机。支持的参数：true,false。
links: D:\path\where\your\link\files\save\content.txt # 链接地址写法如下:
# 新建txt文本，一个链接为一行，将路径填入即可请不要加引号，在软件运行前就准备好。
# D:\path\where\your\link\txt\save\content.txt 一个链接一行。
max_retries:
download: 5 # 最大的下载任务的重试次数。
upload: 3 # 最大的上传任务的重试次数。
max_tasks:
download: 3 # 最大同时下载的任务数。
upload: 3 # 最大同时上传的任务数。
proxy: # 代理部分，如不使用请全部填null注意冒号后面有空格，否则不生效导致报错。
enable_proxy: true # 是否开启代理。支持的参数：true,false。
hostname: 127.0.0.1 # 代理的ip地址。
scheme: socks5 # 代理的类型。支持的参数：http,socks4,socks5。
port: 10808 # 代理ip的端口。支持的参数：0~65535。
username: null # 代理的账号，没有就填null。
password: null # 代理的密码，没有就填null。
save_directory: F:\directory\media\where\you\save # 下载的媒体保存的目录（支持通配符）。
session_directory: F:\directory\session\where\you\save # 会话的保存目录（支持通配符）。
temp_directory: F:\directory\temp\where\you\save # 缓存保存的目录（支持通配符）。-
目前
save_directory支持的通配符如下表所示：通配符 意义 %CHAT_ID%以实际 频道ID作为指定路径填充。%CHAT_NAME%以实际 频道名作为指定路径填充（≥v1.9.6）。%MIME_TYPE%以实际 文件类型作为指定路径填充。 -
用法示例1：
F:\directory\media\%CHAT_ID%
-
用法示例2（≥v1.9.6）：
F:\directory\media\%CHAT_NAME%
-
用法示例3：
F:\directory\media\%MIME_TYPE%
-
用法示例4：
F:\directory\media\%CHAT_NAME%\%CHAT_ID%\%MIME_TYPE%
Note
全局配置文件通常无需自行配置，此处旨在介绍全局配置文件中各参数的含义。
部分参数支持通过机器人设置进行修改。
console_log_level: WARNING # 在终端显示的最低日志类型。
export_table:
count: false # 控制运行结束时是否导出下载计数统计表。
link: false # 控制运行结束时是否导出下载链接统计表。
file_log_level: INFO # 在TRMD_LOG.log文件中记录的最低日志类型。
forward_type: # 控制/listen_forward与/forward命令可转发的文件类型。
animation: true # GIF类型。
audio: true # 音频类型。
document: true # 文档类型。
photo: true # 图片类型。
text: true # 文本消息类型。
video: true # 视频类型。
voice: true # 语音类型。
video_note: true # 视频笔记类型。
notice: false # 控制机器人启动时候是否发送启动通知。
upload:
delete: false # 控制/listen_forward命令遇到受限内容时,下载上传完成后是否删除已上传完成的本地文件。
download_upload: true # 控制/listen_forward命令遇到受限内容时,是否下载后上传到指定的转发频道。%APPDATA%/TRMD/.CONFIG.yaml~/.config/TRMD/.CONFIG.yaml点击展开
-
链接获取方法：对想要保存的媒体文件点击鼠标右键然后选择复制消息直链如下图所示：
-
目前支持视频和图片两种类型的下载。
-
如果当前复制的链接为多张图片或视频，那么程序会自动下载当前消息所有的内容!
-
要下载评论区里的视频或图片，请直接打开评论区，找到任意一个视频或图片，复制它的消息直链(链接末尾会带
?comment=123456这样的参数，不要删除它)。这个链接可以用来下载评论区里的所有视频和图片。注意最好不要手动在链接后面添加?comment=参数，推荐通过复制的方式获取正确链接，否则可能会错误地解析成正文内容。 -
links的文本写法1如下图所示：
-
你所需要下载的视频前提是你当前的Telegram账号，在此视频链接的频道中，否则会报错无法下载！！！
-
常见的错误写法：
- 如上图所示，在提交的下载任务中，存在多个前缀相同但参数不同的链接（如
?comment、?single或?single&comment）。
- 当链接包含
?comment参数时，会自动下载原始消息及其评论区内容。 - 如果同时提交相同前缀但无
?comment的链接，会导致同一资源被重复添加至下载队列。 - 若前一次任务尚未完成，重复提交相同资源会触发任务冲突，进而引发下载异常。
- 仅需提交一个完整链接（如带
?comment的版本），系统会自动处理原始内容及评论区，无需额外提交无参数版本。 - 避免重复提交相同资源，确保每条链接的
t.me/c/<频道>/<消息ID>部分唯一，防止任务冗余。 - 由于这些链接的频道名和消息ID完全一致，实际上指向的是同一资源的不同表现形式。
- 但请注意以下参数的功能差异：
?comment用于标识是否下载评论区内容。?single用于在媒体组中指定仅下载该消息ID对应的单个资源。?single&comment用于指定仅下载评论区中该消息ID所对应的内容。
Telegram字段解释如下表所示：字段 解释 ?comment评论区的链接。 ?single单独的链接。 ?single&comment评论区中单独的链接。 /c私密频道的链接。 https://t.me/TEST/111/666频道 TEST话题111的链接。https://t.me/c/1111111111/333/666私密频道 1111111111话题333的链接。Telegram链接组成如下表所示:频道类型 链接组成 正常频道 https://t.me/频道名/消息ID私密频道 https://t.me/c/频道名(10位纯数字)/消息ID话题频道 https://t.me/频道名/话题ID/消息ID私密话题频道 https://t.me/c/频道名(10位纯数字)/话题ID/消息IDTelegram链接所有链接格式如下表所示:"所有"指的是如果有合并发送为一组的文件，则给定一个链接，所有合并发送的文件会被全部下载。
"媒体"指的是视频和图片。
链接 实际频道名 消息ID 解释 https://t.me/TEST/111TEST111下载该链接的所有媒体。 https://t.me/TEST/111?singleTEST111下载该链接的对应的一个媒体。 https://t.me/TEST/111?comment=666TEST111下载该链接的视频图片的同时，下载该链接下方的评论区的对应的一个媒体。 https://t.me/TEST/111?single&comment=666TEST111下载该链接下方的评论区的对应的一个媒体。 https://t.me/c/1111111111/666-1001111111111666下载该私密频道链接的所有媒体。 https://t.me/TEST/111/666TEST666下载该话题链接的所有媒体。 https://t.me/c/1111111111/333/666-1001111111111666下载该私密话题链接的所有媒体。 -
标准链接（无
?comment参数）:- 仅下载消息正文内容（即频道/群组中直接发布的原始消息）。
- 不包含评论区内容，即使原消息存在评论，也不会被纳入下载任务。
-
带
?comment参数的链接:- 下载消息正文 + 关联的全部评论区内容（完整会话结构）。
- 若原消息无评论区（如频道消息或评论功能关闭），则仅下载消息正文内容，与无参数版本行为一致。
-
非下载评论区的推荐写法如下表所示:
频道类型 链接 正常频道 https://t.me/xxx/111 私密频道 https://t.me/c/xxxxxxxxxx/111 话题频道 https://t.me/xxx/xxx/111 私密话题频道 https://t.me/c/xxxxxxxxxx/xxx/111 自
≥v1.5.8版本起，链接中包含?single或?single&comment参数时，系统将启用单文件下载模式。此模式专为以下场景设计与优化：- 解决
≥1.5.8版本/listen_download当监听到合并发送的文件时，出现重复下载问题。 - 用户需求，仅需从合并发送的多媒体组中提取特定单一文件。
- 用户需求，仅需下载评论区中的单个指定媒体（避免评论区媒体过多时，迟迟下载不到想要的文件）。
参数格式 下载范围 应用场景 xx?single仅下载消息正文中的xx对应媒体文件 从合并图组/视频组提取单文件 ?single&comment=xx仅下载评论区中的xx所对应的媒体文件 获取评论区单独分享的图片/视频 - 此特性仅对 v1.5.8 及以上版本生效。
- 历史版本中这些参数可能被忽略，导致完整内容下载。
-
单一文件提取: 当消息包含多个媒体文件时，使用标准链接附加
?single参数可精准获取首个文件：https://t.me/c/123456789/123?single -
评论区单文件获取: 需从评论区单独下载文件时，应采用复合参数格式：
https://t.me/c/123456789/123?single&comment=xx -
参数互斥原则:
- 避免同时提交同一消息的完整版和单文件版链接。
- 单文件模式与评论区下载模式（
?comment）不可混用。
- 如上图所示，在提交的下载任务中，存在多个前缀相同但参数不同的链接（如
推荐使用Python==3.13.2作为该项目环境(避免使用其他Python版本导致运行时出现报错)。
需自行安装python与git并配置环境变量。
git clone https://github.com/Gentlesprite/Telegram_Restricted_Media_Downloader.git
cd Telegram_Restricted_Media_Downloader
python -m pip install --upgrade pip
pip install -r requirements.txt
python main.py克隆本项目并进入项目目录。
git clone https://github.com/Gentlesprite/Telegram_Restricted_Media_Downloader.git
cd Telegram_Restricted_Media_Downloader更新pip版本(推荐)。
python3 -m pip install --upgrade pip创建并使用虚拟环境(可选)。
python3 -m venv venv
source venv/bin/activate安装程序运行所需依赖并等待全部安装完成。
pip3 install -r requirements.txt运行程序(到这一步就安装完成并运行了，后面是注意事项)。
python3 main.py如果选择创建虚拟环境运行,在下次运行时也需要先激活虚拟环境。
在项目目录下，激活虚拟环境后再运行程序。
source venv/bin/activate
python3 main.py如果提示没有安装pip使用如下命令进行安装：
sudo apt update
sudo apt-get install python3-pip在项目目录下打开终端使用如下命令拉取仓库当前的最新版本：
git pull由于新版本可能使用了新的依赖，使用git pull拉取后，最好更新一下依赖(如果是虚拟环境请先激活再执行)。
pip3 install -r requirements.txtNote
自版本≥v1.8.3起：
用户可在运行前通过命令行参数对软件运行配置进行更多自定义设置。
点击展开
设置命令行运行参数需先在软件目录打开终端，或任意位置打开终端进入软件目录（经常使用建议配置环境变量）。
目前支持的命令行参数用法及解释如下表所示：
| 短参数 | 长参数 | 解释 |
|---|---|---|
-h |
--help |
展示帮助 |
-v |
--version |
展示版本信息 |
-q |
--quiet |
跳过重新配置文件的确认提示 |
-c |
--config |
设置用户配置文件的路径 |
-s |
--session |
设置会话文件的路径 |
-t |
--temp |
设置运行缓存的路径 |
-w |
--web |
通过浏览器运行 |
-m |
--mode |
设置运行模式 |
长参数与短参数最终结果一致。
-
-h、--help参数用法：该参数用于展示帮助。
-
对于生产环境用户（需要先完成前置步骤"3.0.在生产环境中运行"）:
python3 main.py -h
python3 main.py --help
-
对于Windows用户:
TRMD.exe -h
TRMD.exe --help
-
对于Linux用户:
./TRMD -h
./TRMD --help
-
-
-v、--version参数用法：该参数用于展示版本信息。
-
对于生产环境用户（需要先完成前置步骤"3.0.在生产环境中运行"）:
TRMD.exe -v
TRMD.exe --version
-
对于Windows用户:
TRMD.exe -v
TRMD.exe --version
-
对于Linux用户:
./TRMD -v
./TRMD --version
-
-
-q、--quiet参数用法：使用须知 1.该参数用于跳过重新配置文件的确认提示。 2.用户配置文件缺少必要参数时，指定该参数无效。 3.该参数为一次性设置，不记忆。 -
对于生产环境用户（需要先完成前置步骤"3.0.在生产环境中运行"）:
python3 main.py -q
python3 main.py --quiet
-
对于Windows用户:
TRMD.exe -q
TRMD.exe --quiet
-
对于Linux用户:
./TRMD -q
./TRMD --quiet
-
-
-c、--config参数用法：使用须知 1.该参数用于设置用户配置文件的路径。 2.该参数旨在解决多个实例（多开）场景下，避免重复部署软件本体而设计的配置分离方案。 3.该参数需指定一个符合"2.3.配置文件说明(用户配置文件)"格式规范的文件，并且后缀名需为 .yaml。4.当指定的文件路径无效时，将使用软件默认设置。 5.该参数为一次性设置，不记忆。 -
对于生产环境用户（需要先完成前置步骤"3.0.在生产环境中运行"）:
以
Linux系统为例（Winodws系统同理），此处假设用户配置文件位于/home/username/files/example.yaml。python3 main.py -c /home/username/files/example.yaml
python3 main.py --config /home/username/files/example.yaml
-
对于Windows用户:
此处假设用户配置文件位于
C:\files\example.yaml。TRMD.exe -c C:\files\example.yaml
TRMD.exe --config C:\files\example.yaml
-
对于Linux用户:
此处假设用户配置文件位于
/home/username/files/example.yaml。./TRMD -c /home/username/files/example.yaml
./TRMD --config /home/username/files/example.yaml
-
-
-s、--session参数用法：⚠️ 注意：
自版本≥v1.8.5起：
-s、--session参数在设置后将被保存到用户配置文件的session_directory参数中，下次使用时无需重复指定，除非需要修改该设置。使用须知 1.该参数用于设置会话文件的路径。 2.软件会在用户登录成功时后，默认在运行目录下生成 session文件夹，用于保存当前账号信息，以便后续快速登录。3.该参数旨在解决多账号登录场景下需手动重命名会话文件的问题，使用该参数用户可通过直接指定不同路径，选择对应账号进行登录。 4.该参数需指定一个文件夹，可包含已有的 .session文件，指定为空文件夹或不存在时，登录后将在该路径自动生成会话文件。5.该参数设置后会被记忆，下次无需重复设置（ ≥v1.8.5）。-
对于生产环境用户（需要先完成前置步骤"3.0.在生产环境中运行"）:
以
Linux系统为例（Winodws系统同理），此处假设会话文件位于/home/username/files/session。python3 main.py -s /home/username/files/session
python3 main.py --session /home/username/session -
对于Windows用户:
此处假设会话文件位于
C:\files\session。TRMD.exe -s C:\files\session
TRMD.exe --session C:\files\session
-
对于Linux用户:
此处假设会话文件位于
/home/username/files/session。./TRMD -s /home/username/files/session
./TRMD --session /home/username/files/session
-
-
-t、--temp参数用法：⚠️ 注意：
自版本≥v1.8.5起：
-t、--temp参数在设置后将被保存到用户配置文件的temp_directory参数中，下次使用时无需重复指定，除非需要修改该设置。使用须知 1.该参数用于设置运行缓存的路径。 2.缓存即软件运行过程中，记录下载和上传信息的存储中转站。 3.断点续传的实现同样离不开缓存机制的设计，用户可根据实际需求自定义缓存存放的路径。 4.该参数需指定一个文件夹，指定为空文件夹或不存在时，运行时将在该路径自动生成生成缓存文件。 5.该参数设置后会被记忆，下次无需重复设置（ ≥v1.8.5）。-
对于生产环境用户（需要先完成前置步骤"3.0.在生产环境中运行"）:
以
Linux系统为例（Winodws系统同理），此处假设缓存文件位于/home/username/files/temp。python3 main.py -t /home/username/files/temp
python3 main.py --temp /home/username/temp
-
对于Windows用户:
此处假设缓存文件位于
C:\files\temp。TRMD.exe -t C:\files\temp
TRMD.exe --temp C:\files\temp
-
对于Linux用户:
此处假设缓存文件位于
/home/username/files/temp。./TRMD -t /home/username/files/temp
./TRMD --temp /home/username/files/temp
-
-
-w、--web参数用法：使用须知 1.该参数用于控制是否通过浏览器运行。 2.该参数设置后将自动使用默认浏览器作为软件的终端界面，并自动打开（运行环境不支持时，需手动打开）。 3. Web配置信息会在运行的终端提供，以便启动时输入账号密码。4.关闭浏览器窗口即代表退出程序，且不会保留任何会话状态。 5.可在此参数后指定一个 0~65535范围内的端口号，若不指定，将随机分配端口。6.该参数为一次性设置，不记忆。 -
对于生产环境用户（需要先完成前置步骤"3.0.在生产环境中运行"）:
此处假设使用随机端口。
python3 -w
python3 --web
-
对于Windows用户:
此处假设使用
1024端口。TRMD.exe -w 1024
TRMD.exe --web 1024
-
对于Linux用户:
此处假设使用随机端口。
./TRMD -w
./TRMD --web
-
-
-m、--mode参数用法：使用须知 1.该参数用于设置运行模式。 2.该参数为 -w、--web命令设置启动模式，控制是否存储web模式的会话状态。3.该参数为一次性设置，不记忆。 -
运行模式分为
ONCE、SESSION模式，默认为ONCE模式，区别如下表所示：模式 效果 ONCE不保存会话，在关闭、刷新网页后软件随之退出。 SESSION保存会话，在关闭、刷新网页后软件保持运行，在下次访问时自动恢复。 -
对于生产环境用户（需要先完成前置步骤"3.0.在生产环境中运行"）:
设置
SESSION模式时，保存会话，在关闭、刷新网页后软件保持运行，在下次访问时自动恢复。TRMD.exe -w -m SESSION
TRMD.exe --web --mode SESSION
-
对于Windows用户:
设置
ONCE模式时，不保存会话，在关闭、刷新网页后软件随之退出。TRMD.exe -w -m ONCE
TRMD.exe --web --mode ONCE
-
对于Linux用户:
不设置时，
-m、--mode默认为ONCE模式，不保存会话，在关闭、刷新网页后软件随之退出。./TRMD -w
./TRMD --web
-
推荐使用Python==3.13.2作为该项目环境(避免使用其他Python版本导致编译过程中或编译完成后出现报错)。
-
同"3.0.在生产环境中运行"前置步骤一致。
-
然后执行编译代码(建议使用虚拟环境，避免添加不必要的库，从而减小输出的文件大小)。
python build.pyDocker环境运行配置文件模板参考（前提：需完全按照后续教程提供的命令启动Docker）：
api_hash: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
api_id: 'xxxxxxxx'
bot_token: 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11 # Docker运行推荐使用机器人，通过"电报机器人(bot_token)申请及使用教程"自行申请。
download_type:
- video
- photo
- document
- audio
- voice
- animation
- video_note
is_shutdown: false
links: /app/TRMD/links.txt # 主机的路径为："config/links.txt"。
max_retries:
download: 5
upload: 3
max_tasks:
download: 3
upload: 3
proxy:
enable_proxy: true # 如果网络能直接访问Telegram服务器，设置为false。
hostname: 192.168.1.10 # 此处为示例，每个人地址不同，填写提供代理服务器主机的ip地址，通常使用ifconfig查看。
scheme: socks5 # 代理的类型。支持的参数：http,socks4,socks5。
port: 10808 # 此处为示例，实际使用的代理软件不同端口也不同，填写主机的代理ip的端口。支持的参数：0~65535。
username: null # 代理的账号，没有就填null。
password: null # 代理的密码，没有就填null。
save_directory: /app/downloads/%CHAT_NAME%/%MIME_TYPE% # 主机的路径为："downloads/%CHAT_NAME%/%MIME_TYPE%"。
session_directory: /app/sessions # 主机的路径为："sessions/"。
temp_directory: /app/temp # 主机的路径为："temp/"。方式1：
-
确保
git、docker、docker-compose已安装并配置环境变量。 -
使用
git克隆仓库:git clone https://github.com/Gentlesprite/Telegram_Restricted_Media_Downloader.git
-
进入项目文件夹：
cd Telegram_Restricted_Media_Downloader -
首次使用时需要配置文件：
docker-compose run --rm trmd
-
已配置完成的情况下：
docker-compose up -d
方式2：
-
确保
docker已安装并配置环境变量。 -
使用
docker从远程仓库拉取镜像：docker pull gentlesprite/telegram_restricted_media_downloader:latest
-
需要使用时，创建并启动容器：
docker run -it \ --name trmd \ -v ./config:/app/TRMD \ -v ./sessions:/app/sessions \ -v ./downloads:/app/downloads \ -v ./temp:/app/temp \ -e TZ=Asia/Shanghai \ --restart unless-stopped \ gentlesprite/telegram_restricted_media_downloader:latest
-
如果是通过
Windows使用wsl2运行docker：docker run -it --name trmd -v ./config:/app/TRMD -v ./sessions:/app/sessions -v ./downloads:/app/downloads -v ./temp:/app/temp -e TZ=Asia/Shanghai --restart unless-stopped gentlesprite/telegram_restricted_media_downloader:latest
-
不再使用时，停止并删除容器：
docker stop trmd && docker rm trmd
方式3，使用web模式运行（≥1.9.3）：
-
确保
docker已安装并配置环境变量。 -
使用
docker从远程仓库拉取镜像，注意软件版本需要≥1.9.3：docker pull gentlesprite/telegram_restricted_media_downloader:latest
-
创建并启动容器，
web模式使用2921端口：docker run -d \ --name trmd \ -v ./config:/app/TRMD \ -v ./sessions:/app/sessions \ -v ./downloads:/app/downloads \ -v ./temp:/app/temp \ -p 2921:2921 \ -w /app \ -e TZ=Asia/Shanghai \ --restart unless-stopped \ gentlesprite/telegram_restricted_media_downloader:latest \ python main.py --config /app/TRMD/config.yaml --web 2921 --mode SESSION
-
如果是通过
Windows使用wsl2运行docker：docker run -d --name trmd -v ./config:/app/TRMD -v ./sessions:/app/sessions -v ./downloads:/app/downloads -v ./temp:/app/temp -p 2921:2921 -w /app -e TZ=Asia/Shanghai --restart unless-stopped gentlesprite/telegram_restricted_media_downloader:latest python main.py --config /app/TRMD/config.yaml --web 2921 --mode SESSION
-
查看运行日志：
docker logs trmd
-
正常运行时会在运行日志中输出一个
Web配置表格，类似下表：属性 内容 IP地址 127.0.0.1端口 2921账号 cLJqKG3b密码 AiJaKSObcRCZ访问链接 http://127.0.0.1:2921账号密码由系统随机生成，使用浏览器打开http://127.0.0.1:2921网页输入账号密码即可进入。
-
不再使用时，停止并删除容器：
docker stop trmd && docker rm trmd
Telegram:@Gentlesprite
