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即可。退出软件。 -
/help命令使用教程，如下图所示：
-
点击菜单可以显示机器人可用的命令，如下图所示：
-
/download命令使用教程，如下图所示：-
方式一：
- 只要发送了正确的下载命令，终端就会创建对应的下载任务，如下图所示：
-
方式二：
-
该功能为版本
≥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%时，代表该链接还存在其他用户未指定的文件类型，但实际用户所指定的类型已经下载完成了，是正常情况。
计数统计表的使用，如下图所示:
-
-
/forward命令使用教程：
Note
目前转发功能暂不支持从话题频道转发。
消息能否转发，在于频道是否开启了限制保存内容功能。
如果无法转发，机器人会在聊天框提供一个下载按钮。
# 语法格式如下：
/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 https://t.me/B https://t.me/n # /listen_download命令后面跟多个以空格分割的频道链接。 # 取消监听方法： # 再次发送与之前创建监听的命令一样的,即可得到机器人发送给用户的一个内联键盘,点击确认即可。 # 如果之前已经创建过监听,已创建的监听就会提示重复并询问是否关闭。 # 注意:由于电报对内联键盘回调数据位数的限制为64位,若回调数据超过64位,则无法通过内联键盘进行取消,只能重启软件。 # 举例： # 例如取消https://t.me/A https://t.me/B # 则再次发送: # /listen_download https://t.me/A https://t.me/B # 此时在机器人发送的两个内联键盘,分别选择确定即可取消。 # 例如取消https://t.me/n # 则再次发送: # /listen_download https://t.me/n # 此时所有监听任务都被取消了。
-
/listen_forward命令使用教程：/listen_download监听转发用于，实时监听该链接的最新消息进行下载。与
/forward命令一样，消息能否转发，在于频道是否开启了限制保存内容功能。在用户发送了正确的监听命令后，会收到机器人的成功提示，当被监听的频道有任何新内容时，就会自动转发至用户所指定的频道。
# 语法格式如下： /listen_forward https://t.me/A https://t.me/B # https://t.me/A代表要监听的频道。 # https://t.me/B代表要转发到的频道。 /listen_forward 监听频道 转发频道 # /listen_forward命令必须填写监听频道与转发频道。 # 取消监听方法： # 再次发送与之前创建监听的命令一样的,即可得到机器人发送给用户的一个内联键盘,点击确认即可。 # 如果之前已经创建过监听,已创建的监听就会提示重复并询问是否关闭。 # 注意:由于电报对内联键盘回调数据位数的限制为64位,若回调数据超过64位,则无法通过内联键盘进行取消,只能重启软件。 # 举例： # 例如取消监听频道https://t.me/A转发到https://t.me/B频道的监听转发。 # 则再次发送: # /listen_forward https://t.me/A https://t.me/B # 此时在机器人发送的内联键盘,选择确定即可取消。
-
/listen_info命令使用教程：/listen_info用于查看当前已经创建的监听信息，直接发送即可。/listen_info
- 频道独占原则:
- 每个频道同一时间只能激活一种监听模式（下载或转发）。
- 对于
/listen_forward命令，"同一频道"特指被监听的源频道。 - 转发目标频道不受此限制，仍可通过
/listen_download创建下载任务。
- 操作限制:
- 当
频道A正在监听转发到频道B时:- 可以同时在
频道B设置下载监听。 - 但
频道B的下载监听不会响应来自频道A的转发消息。
- 可以同时在
- 监听切换流程:
- 必须先通过同一命令(注册监听时的命令)来取消现有监听。
- 然后才能创建新的监听事件。
# 这里只是介绍每个参数的含义,软件会详细地引导配置参数。
# 如果是按照软件的提示填,选看。如果是手动打开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。
- video
- photo
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_download_task: 5 # 最大的下载任务数,值过高可能会导致网络相关问题。支持的参数:所有>0的整数。
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 # 下载的媒体保存的目录。(不支持网络路径)-
链接获取方法：对想要保存的媒体文件点击鼠标右键然后选择复制消息直链如下图所示：
-
目前支持视频和图片两种类型的下载。
-
如果当前复制的链接为多张图片或视频，那么程序会自动下载当前消息所有的内容!
-
要下载评论区里的视频或图片，请直接打开评论区，找到任意一个视频或图片，复制它的消息直链(链接末尾会带
?comment=123456这样的参数，不要删除它)。这个链接可以用来下载评论区里的所有视频和图片。注意最好不要手动在链接后面添加?comment=参数，推荐通过复制的方式获取正确链接，否则可能会错误地解析成正文内容。 -
links的文本写法1如下图所示：
-
你所需要下载的视频前提是你当前的Telegram账号，在此视频链接的频道中，否则会报错无法下载！！！
-
常见的错误写法(请不要这样写)：
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参数的链接:- 下载消息正文 + 关联的全部评论区内容（完整会话结构）。
- 若原消息无评论区（如频道消息或评论功能关闭），则仅下载消息正文内容，与无参数版本行为一致。
在提交的下载任务中，存在多个前缀相同但参数不同的链接（如
?comment、?single或?single&comment）。由于这些链接的频道名和消息ID完全一致，实际上指向的是同一资源的不同表现形式。- 当链接包含
?comment参数时，会自动下载原始消息及其评论区内容。 - 如果同时提交相同前缀但无
?comment的链接，会导致同一资源被重复添加至下载队列。 - 若前一次任务尚未完成，重复提交相同资源会触发任务冲突，进而引发下载异常。
- 仅需提交一个完整链接（如带
?comment的版本），系统会自动处理原始内容及评论区，无需额外提交无参数版本。 - 避免重复提交相同资源，确保每条链接的
t.me/c/<频道>/<消息ID>部分唯一，防止任务冗余。
非下载评论区的推荐写法如下表所示:
频道类型 链接 正常频道 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.pygit clone https://github.com/Gentlesprite/Telegram_Restricted_Media_Downloader.git
cd Telegram_Restricted_Media_Downloader
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.txtTelegram:@Gentlesprite
