A telegram downloader on windows and linux platform based on Python.
Note
由于本项目提供的Linux版本可能对较早版本的Linux系统兼容性较差。
若无法运行的Linux用户请阅读:"3.0.在生产环境中运行(对于Linux用户)"。
如果你遇到任何问题,请先阅读:"常见问题及解决方案汇总"。
没有找到解决方案再进群或私聊提问。
作者:Gentlesprite
B站视频教程:点击观看
Telegram交流群:点击加入
软件免费使用!并且在GitHub开源,如果你付费那就是被骗了。
蓝奏云:点击跳转下载 密码:ceze
Github:点击跳转下载
-
对于Windows11用户,
Windows Terminal默认已经安装好,可跳过下载的步骤,直接前往第3步。(将Windows Terminal设为默认终端) -
对于Windows10用户,推荐使用
Windows Terminal作为默认终端,仅作为推荐安装,无论安装与否不会影响本软件的使用,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本地文件目标频道上传本地的文件到指定频道。 /download_chat/download_chat 频道链接下载指定频道并支持通过内联键盘自定义内容过滤。 -
/help命令使用教程,如下图所示: -
点击菜单可以显示机器人可用的命令,如下图所示:
-
/download命令使用教程,如下图所示: -
/table命令使用教程:需要注意的是,这个表格是实时的状态,并不是最终下载完成的结果,每一次使用它都会随着当前的下载记录而更新。
链接统计表的使用,如下图所示:
注意:由于早期代码设计缺陷,链接统计表为后续支持的功能:
-
链接统计表仅会统计所有支持的类型,并不会只统计用户当前所选择的类型。
-
链接统计表对于评论区媒体的统计,会出现总数统计错误的问题,体现在总数为
1,小于当前的下载数,完成率>>100%的问题(该问题已在≥v1.5.9修复)。 -
当用户未选择下载所有支持的类型时,在用户所选择的类型下载完成后(或使用机器人发送链接统计表),尽管所有用户指定类型的文件已经下载完成,当链接统计表显示
完成率不为100%时,代表该链接还存在其他用户未指定的文件类型,但实际用户所指定的类型已经下载完成了,是正常情况。 -
版本
≥v1.6.5起已支持导出表格功能,通过该命令可在运行时控制是否在退出后导出指定类型的表格。
计数统计表的使用,如下图所示:
-
-
/forward命令使用教程:
Note
消息能否转发,在于频道是否开启了限制保存内容功能。
如果无法转发,机器人会在聊天框提供一个下载按钮与下载后上传按钮(≥v1.6.7)。
自版本≥v1.7.5起:
为确保"受限转发"功能顺利完成,在下载后上传过程中,将忽略配置文件中设置的下载类型限制,仅遵循[上传设置]中的类型过滤规则。
自版本≥v1.6.9起:
/forward将支持过滤转发类型。
可通过[帮助页面]->[设置]->[转发设置]进行修改。
- 转发消息语法:
/forward 频道A 频道B 起始ID 结束ID
- 实例:
/forward https://t.me/test https://t.me/test2 1 500
- 代表转发
https://t.me/test频道中从消息ID=1到结束ID=500的消息到https://t.me/test2频道。- 若需转发至个人的收藏夹,请使用
https://t.me/用户名(用户名就是个人账户信息里@后面那一串)。
- 若需转发至个人的收藏夹,请使用
- 在个人信息中查看到用户名为@developer。
- 此时使用
/forward https://t.me/test https://t.me/developer 1 500命令。 - 代表转发
https://t.me/test频道中从消息ID=1到结束ID=500的消息到个人收藏夹。
- 此时使用
/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命令使用教程:
Note
自版本≥v1.6.7起:
当检测到"受限转发"时,自动采用"下载后上传"的方式(默认开启)。
当下载并完成上传后,可选择是否删除本地文件(默认关闭)。
并且可通过[帮助页面]->[设置]->[上传设置]进行修改。
自版本≥v1.7.5起:
为确保"受限转发"功能顺利完成,在下载后上传过程中,将忽略配置文件中设置的下载类型限制,仅遵循[上传设置]中的类型过滤规则。
自版本≥v1.6.9起:
/listen_forward将支持过滤转发类型。
可通过[帮助页面]->[设置]->[转发设置]进行修改。
-
/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命令使用教程:
-
/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 - 普通用户:单个文件最大上传大小为
/download_chat命令使用教程:
-
/download_chat下载指定频道。- 与
/download不同的是:/download_chat支持通过机器人发送的内联键盘进行自定义内容过滤。 - 目前该功能支持按日期范围、文件类型来过滤要下载的内容。
- 使用该命令后,需要通过操作机器人回复中的内联键盘,来设置过滤器、执行任务或取消任务。
- 需要注意的是,在上一个
/download_chat命令任务未执行或取消前,无法发起新的/download_chat命令来创建下载任务。 - 自版本
≥v1.7.5起,/download_chat命令创建的下载任务过滤条件将完全遵循用户在内联键盘中的设置,意味着该不会遵循配置文件中的任何规则(例如配置文件中的下载文件类型设置)。
- 与
-
下载指定频道语法:
/download_chat 频道链接
-
发送命令后,设置过滤器为可选操作,但必须手动点击"执行任务"或"取消任务"以继续或终止流程,否则该命令将始终处于等待状态,并阻塞新的
/download_chat命令。
# 这里只是介绍每个参数的含义,软件会详细地引导配置参数。
# 如果是按照软件的提示填,选看。如果是手动打开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
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: 5 # 最大同时下载的任务数。
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 # 下载的媒体保存的目录(支持通配符,不支持网络路径)。-
目前
save_directory支持的通配符如下表所示:通配符 意义 %CHAT_ID%以实际 频道ID作为指定路径填充。%MIME_TYPE%以实际 文件类型作为指定路径填充。 -
用法示例1:
F:\directory\media\%CHAT_ID%
-
用法示例2:
F:\directory\media\%MIME_TYPE%
-
用法示例3:
F:\directory\media\%CHAT_ID%\%MIME_TYPE%
# 全局配置文件无需自行配置,这里只是介绍每个参数的含义。
# Windows存放路径:%APPDATA%/TRMD
# Linux存放路径:~/.config/TRMD
# 部分参数可以通过机器人设置修改。
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 # 语音类型。
notice: false # 控制机器人启动时候是否发送启动通知。
upload:
delete: false # 控制/listen_forward命令遇到受限内容时,下载上传完成后是否删除已上传完成的本地文件。
download_upload: true # 控制/listen_forward命令遇到受限内容时,是否下载后上传到指定的转发频道。-
链接获取方法:对想要保存的媒体文件点击鼠标右键然后选择复制消息直链如下图所示:
-
目前支持视频和图片两种类型的下载。
-
如果当前复制的链接为多张图片或视频,那么程序会自动下载当前消息所有的内容!
-
要下载评论区里的视频或图片,请直接打开评论区,找到任意一个视频或图片,复制它的消息直链(链接末尾会带
?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.txt推荐使用Python==3.13.2作为该项目环境(避免使用其他Python版本导致编译过程中或编译完成后出现报错)。
-
同"在生产环境中运行"前置步骤一致。
-
然后执行编译代码(建议使用虚拟环境,避免添加不必要的库,从而减小输出的文件大小)。
python build.pyTelegram:@Gentlesprite