yt-dlp-downloader
Skill1.1k starsChanged 22 days agoApache-2.0View on GitHub
Download videos and audio from YouTube and 1000+ websites using yt-dlp. Use when the user provides a video URL, asks to download videos, or mentions downloading content from video platforms like YouTube, Bilibili, Vimeo, etc.
- Installs packages
5 other projects use a version of this.
Trending
More talk lately.thin dataabout the whole repository
Most recently taken up by
- HeteroCat/heterocat-skillstheir own version, first seen Nov 8, 2026
- johnqtcg/awesome-skillstheir own version, first seen Jul 9, 2026
- DawnMoon1542/agents-skillstheir own version, first seen Jun 9, 2026
- xiaolinVV/agents-skillstheir own version, first seen Mar 8, 2026
- MapleShaw/yt-dlp-downloader-skilltheir own version, first seen Jan 24, 2026
Who's talking about DemonDamon/AgenticX
The biggest 1 of 1 mention linking to the repository that our crawl found. Each line is their own headline.
Used with
Projects with it also use agent-browser.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
VercelSkillagent-browser
Automates browser interactions for web testing, form filling, screenshots, and data extraction. Use when the user needs to navigate websites, interact with web pages, fill forms, take screenshots, test web applications, or extract information from web pages.
Also in 3 projects that use this
Other versions5 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 5
- MapleShaw/yt-dlp-downloader-skill★ 202same name
- johnqtcg/awesome-skills★ 30same name
- DawnMoon1542/agents-skills★ 8same name
- HeteroCat/heterocat-skills★ 4same name
- xiaolinVV/agents-skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository21 other files it gives its agents.
- AGENTS.mdAGENTS.md
- mobile/AGENTS.mdAGENTS.md
- agenticx-fusion-digestSkill
- brainstormingSkill
- code-deep-researchSkill
- code-module-summariesSkill
- dispatching-parallel-agentsSkill
- executing-plansSkill
- finishing-a-development-branchSkill
- oss-visual-brandingSkill
- receiving-code-reviewSkill
- recording-investor-product-demoSkill
- requesting-code-reviewSkill
- subagent-driven-developmentSkill
- systematic-debuggingSkill
- test-driven-developmentSkill
- using-git-worktreesSkill
- using-superpowersSkill
- verification-before-completionSkill
- writing-plansSkill
- writing-skillsSkill
The file
We split this skill into the rules it gives an agent
11 rules. 2 are common, 5 are distinctive, and 4 are very specific to this project.
2
Common
Most of the 5 edited versions we read keep these.
5
Distinctive
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Common: line 12
When the user provides a video URL, automatically:
- Distinctive: line 460
When integrating into Python code:
- Distinctive: line 839
Check PATH if using binary
- Distinctive: line 972
Check if video is available
- Very specific: line 974
Check if site is supported: yt-dlp --list-extractors
- Very specific: line 977
Use concurrent fragments: yt-dlp --concurrent-fragments 8 <URL>
- Very specific: line 978
Use external downloader: yt-dlp --downloader aria2c <URL>
- Common: line 982
When user provides a video URL:
- Distinctive: line 1009
Execute download: - Run appropriate yt-dlp command
- Very specific: line 1013
If network error → Try with cookies: yt-dlp --cookies cookies.txt <URL>
- Distinctive: line 1014
If still fails → Check proxy configuration
“Common” is measured: kept by at least 6 in 10 of the 5 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
yt-dlp Video Downloader
Download videos and audio from YouTube, Bilibili, Vimeo, and 1000+ other websites using yt-dlp.
Quick Start
When the user provides a video URL, automatically:
- 检测环境
- 检测操作系统(macOS/Linux/Windows)
- 检测 Python 和 pip 是否可用
- 检测包管理器(brew/apt-get 等)
- 检查 yt-dlp 是否已安装
如果已安装,会显示版本号;如果未安装,继续下一步。yt-dlp --version - 如果未安装,根据环境自动安装
# macOS/Linux: 优先使用 pip3 pip3 install yt-dlp # 如果没有 pip3,使用 pip pip install yt-dlp # macOS 也可以使用 Homebrew brew install yt-dlp - (可选)检查并安装 FFmpeg
# 检查 FFmpeg ffmpeg -version # macOS brew install ffmpeg # Linux (Debian/Ubuntu) sudo apt-get install ffmpeg - 检测代理配置(如果需要)
# 安装脚本会自动检测代理 python3 .cursor/skills/yt-dlp-downloader/install_yt_dlp.py # 或手动检测 echo $HTTP_PROXY # 检查环境变量 networksetup -getwebproxy Wi-Fi # macOS 系统代理 - 下载视频
# 基本下载 yt-dlp <视频URL> # 如果需要代理 yt-dlp --proxy http://127.0.0.1:33210 <视频URL> # 如果需要 cookies yt-dlp --cookies cookies.txt <视频URL> # 代理 + cookies yt-dlp --proxy http://127.0.0.1:33210 --cookies cookies.txt <视频URL>
完整自动化流程示例:
# 1. 检测环境
import platform
import subprocess
import shutil
os_name = platform.system()
has_pip3 = shutil.which("pip3") is not None
has_pip = shutil.which("pip") is not None
# 2. 检查安装
try:
version = subprocess.check_output(["yt-dlp", "--version"], text=True).strip()
print(f"yt-dlp 已安装: {version}")
except FileNotFoundError:
# 3. 自动安装
pip_cmd = "pip3" if has_pip3 else "pip"
subprocess.run([pip_cmd, "install", "yt-dlp"], check=True)
print("yt-dlp 安装完成")
# 4. 下载视频
subprocess.run(["yt-dlp", video_url])Installation
快速安装(推荐)
使用提供的安装脚本:
# Python 脚本(跨平台)
python3 .cursor/skills/yt-dlp-downloader/install_yt_dlp.py
# Shell 脚本(macOS/Linux)
bash .cursor/skills/yt-dlp-downloader/install_yt_dlp.sh
# 或
chmod +x .cursor/skills/yt-dlp-downloader/install_yt_dlp.sh
./.cursor/skills/yt-dlp-downloader/install_yt_dlp.sh安装脚本会自动:
- 检测操作系统和 Python 环境
- 检查 yt-dlp 是否已安装
- 如果未安装,根据环境自动选择安装方式
- 可选:检查并安装 FFmpeg
环境检测和自动安装流程
在使用 yt-dlp 之前,应该:
- 检测操作系统和 Python 环境
- 检查 yt-dlp 是否已安装
- 如果未安装,根据环境自动安装
- 检查并安装 FFmpeg(可选但推荐)
环境检测脚本
Python 脚本示例:
import sys
import platform
import subprocess
import shutil
def detect_environment():
"""检测当前环境"""
os_name = platform.system()
os_version = platform.release()
python_version = sys.version_info
is_mac = os_name == "Darwin"
is_linux = os_name == "Linux"
is_windows = os_name == "Windows"
# 检测包管理器
has_brew = shutil.which("brew") is not None
has_apt = shutil.which("apt-get") is not None
has_pip = shutil.which("pip") is not None
has_pip3 = shutil.which("pip3") is not None
return {
"os": os_name,
"os_version": os_version,
"python_version": f"{python_version.major}.{python_version.minor}.{python_version.micro}",
"is_mac": is_mac,
"is_linux": is_linux,
"is_windows": is_windows,
"has_brew": has_brew,
"has_apt": has_apt,
"has_pip": has_pip,
"has_pip3": has_pip3,
}
def check_yt_dlp_installed():
"""检查 yt-dlp 是否已安装"""
try:
result = subprocess.run(
["yt-dlp", "--version"],
capture_output=True,
text=True,
timeout=5
)
if result.returncode == 0:
return True, result.stdout.strip()
return False, None
except (FileNotFoundError, subprocess.TimeoutExpired):
return False, None
def install_yt_dlp(env_info):
"""根据环境安装 yt-dlp"""
# 优先使用 pip3,其次 pip
pip_cmd = "pip3" if env_info["has_pip3"] else "pip"
if not env_info["has_pip"] and not env_info["has_pip3"]:
raise RuntimeError("未找到 pip 或 pip3,请先安装 Python 包管理器")
print(f"使用 {pip_cmd} 安装 yt-dlp...")
result = subprocess.run(
[pip_cmd, "install", "yt-dlp"],
capture_output=True,
text=True
)
if result.returncode == 0:
print("yt-dlp 安装成功!")
return True
else:
print(f"安装失败: {result.stderr}")
return False
def check_ffmpeg_installed():
"""检查 FFmpeg 是否已安装"""
try:
result = subprocess.run(
["ffmpeg", "-version"],
capture_output=True,
text=True,
timeout=5
)
if result.returncode == 0:
return True
return False
except (FileNotFoundError, subprocess.TimeoutExpired):
return False
def install_ffmpeg(env_info):
"""根据环境安装 FFmpeg"""
if env_info["is_mac"] and env_info["has_brew"]:
print("使用 Homebrew 安装 FFmpeg...")
subprocess.run(["brew", "install", "ffmpeg"])
elif env_info["is_linux"] and env_info["has_apt"]:
print("使用 apt-get 安装 FFmpeg...")
subprocess.run(["sudo", "apt-get", "update"])
subprocess.run(["sudo", "apt-get", "install", "-y", "ffmpeg"])
elif env_info["is_windows"]:
print("Windows 请手动安装 FFmpeg:")
print("1. 访问 https://www.gyan.dev/ffmpeg/builds")
print("2. 下载并解压")
print("3. 将 bin 目录添加到 PATH 环境变量")
else:
print("无法自动安装 FFmpeg,请手动安装")
# 使用示例
if __name__ == "__main__":
# 1. 检测环境
env = detect_environment()
print(f"操作系统: {env['os']} {env['os_version']}")
print(f"Python 版本: {env['python_version']}")
# 2. 检查 yt-dlp
is_installed, version = check_yt_dlp_installed()
if is_installed:
print(f"yt-dlp 已安装,版本: {version}")
else:
print("yt-dlp 未安装,开始安装...")
install_yt_dlp(env)
# 3. 检查 FFmpeg(可选)
if check_ffmpeg_installed():
print("FFmpeg 已安装")
else:
print("FFmpeg 未安装(可选,但推荐安装)")
install_ffmpeg(env)Shell 脚本示例(bash/zsh):
#!/bin/bash
# 检测环境
detect_env() {
OS="$(uname -s)"
case "${OS}" in
Linux*) MACHINE=Linux;;
Darwin*) MACHINE=Mac;;
CYGWIN*) MACHINE=Cygwin;;
MINGW*) MACHINE=MinGW;;
*) MACHINE="UNKNOWN:${OS}"
esac
echo "检测到操作系统: $MACHINE"
}
# 检查 yt-dlp 是否安装
check_yt_dlp() {
if command -v yt-dlp &> /dev/null; then
VERSION=$(yt-dlp --version)
echo "yt-dlp 已安装,版本: $VERSION"
return 0
else
echo "yt-dlp 未安装"
return 1
fi
}
# 安装 yt-dlp
install_yt_dlp() {
echo "开始安装 yt-dlp..."
# 优先使用 pip3
if command -v pip3 &> /dev/null; then
pip3 install yt-dlp
elif command -v pip &> /dev/null; then
pip install yt-dlp
else
echo "错误: 未找到 pip 或 pip3"
exit 1
fi
}
# 检查 FFmpeg
check_ffmpeg() {
if command -v ffmpeg &> /dev/null; then
echo "FFmpeg 已安装"
return 0
else
echo "FFmpeg 未安装(可选)"
return 1
fi
}
# 安装 FFmpeg
install_ffmpeg() {
case "${MACHINE}" in
Mac)
if command -v brew &> /dev/null; then
echo "使用 Homebrew 安装 FFmpeg..."
brew install ffmpeg
else
echo "请先安装 Homebrew: https://brew.sh"
fi
;;
Linux)
if command -v apt-get &> /dev/null; then
echo "使用 apt-get 安装 FFmpeg..."
sudo apt-get update
sudo apt-get install -y ffmpeg
else
echo "请使用系统包管理器安装 FFmpeg"
fi
;;
*)
echo "请手动安装 FFmpeg"
;;
esac
}
# 主流程
detect_env
if ! check_yt_dlp; then
install_yt_dlp
fi
if ! check_ffmpeg; then
read -p "是否安装 FFmpeg? (y/n) " -n 1 -r
echo
if [[ $REPLY =~ ^[Yy]$ ]]; then
install_ffmpeg
fi
fi手动安装方法
Check Installation
yt-dlp --versionInstall via pip (recommended)
# 优先使用 pip3
pip3 install yt-dlp
# 如果没有 pip3,使用 pip
pip install yt-dlp
# 如果使用 Python 虚拟环境
python3 -m pip install yt-dlpInstall via Homebrew (macOS)
brew install yt-dlpInstall FFmpeg (strongly recommended)
Required for merging video/audio and format conversion.
macOS:
brew install ffmpegLinux (Debian/Ubuntu):
sudo apt-get update
sudo apt-get install ffmpegLinux (Fedora/RHEL):
sudo dnf install ffmpegWindows:
- 访问 https://www.gyan.dev/ffmpeg/builds
- 下载 FFmpeg 构建版本
- 解压到目录(如
C:\ffmpeg) - 将
bin目录添加到系统 PATH 环境变量 - 重启终端验证:
ffmpeg -version
Common Usage Patterns
Download Best Quality Video
yt-dlp <URL>Download Specific Format
# List available formats
yt-dlp -F <URL>
# Download specific format ID
yt-dlp -f <format_id> <URL>Download Audio Only
# Extract audio as MP3
yt-dlp -x --audio-format mp3 <URL>
# Best audio quality
yt-dlp -x --audio-format mp3 --audio-quality 0 <URL>Download with Subtitles
# Download video with Chinese subtitles
yt-dlp --write-subs --sub-langs zh-Hans <URL>
# Download subtitles only
yt-dlp --write-subs --skip-download <URL>Download Playlist
yt-dlp <playlist_URL>Use Proxy
yt-dlp --proxy socks5://127.0.0.1:1080 <URL>Use Browser Cookies (for login-required content)
yt-dlp --cookies-from-browser chrome <URL>Python API Usage
When integrating into Python code:
import yt_dlp
url = '<视频URL>'
# Basic download
ydl_opts = {
'format': 'bestvideo+bestaudio/best',
'outtmpl': '%(title)s.%(ext)s',
}
with yt_dlp.YoutubeDL(ydl_opts) as ydl:
ydl.download([url])Extract Info Without Downloading
import yt_dlp
import json
ydl_opts = {}
with yt_dlp.YoutubeDL(ydl_opts) as ydl:
info = ydl.extract_info(url, download=False)
print(json.dumps(ydl.sanitize_info(info), indent=2))Output Format Options
Save to Specific Directory
yt-dlp -o "~/Downloads/%(title)s.%(ext)s" <URL>Merge as MP4
yt-dlp --merge-output-format mp4 <URL>Supported Sites
yt-dlp supports 1000+ sites including:
- YouTube
- Bilibili
- Vimeo
- TikTok
- Twitch
- SoundCloud
- And many more...
Cookies 使用指南
⚠️ 安全警告
重要:不要分享你的 cookies.txt 文件!
- Cookies 包含你的登录凭证和会话信息,相当于你的账户密码
- 泄露 cookies 可能导致账户被盗用、隐私泄露
- 每个用户必须使用自己的 cookies,不能共享
- 本 skill 中的
cookies-example.txt仅为格式示例,不能直接使用 - 请将
cookies.txt添加到.gitignore,避免误提交到代码仓库
为什么需要 Cookies?
- 访问需要登录的内容
- 绕过 "Sign in to confirm you're not a bot" 错误
- 下载年龄限制的视频
- 访问订阅内容
导出 Cookies(推荐方法)
方法1:使用浏览器扩展(最简单)
- 安装扩展:
- Chrome/Edge: 访问
chrome://extensions/ - 搜索并安装 "Get cookies.txt LOCALLY"
- 扩展地址:https://chromewebstore.google.com/detail/get-cookiestxt-locally/cclelndahbckbenkjhflpdbgdldlbecc
- Chrome/Edge: 访问
- 导出 Cookies:
- 在 YouTube 页面确保已登录
- 点击扩展图标
- 点击 "Export" 或 "Copy"
- 将内容保存为
cookies.txt文件
- 使用 Cookies 下载:
yt-dlp --cookies cookies.txt <URL>
方法2:从浏览器开发者工具手动导出
- 打开 Chrome 开发者工具(F12)
- 切换到 "Application" 标签页
- 左侧找到 "Storage" → "Cookies" →
https://www.youtube.com - 查看所有 cookies(关键 cookies:
LOGIN_INFO、VISITOR_INFO1_LIVE、YSC等) - 使用扩展导出(推荐)或手动创建 cookies.txt 文件
方法3:使用 yt-dlp 直接从浏览器读取(macOS 可能失败)
# Chrome (macOS 上可能无法解密 cookies)
yt-dlp --cookies-from-browser chrome <URL>
# Firefox
yt-dlp --cookies-from-browser firefox <URL>注意:macOS 上 Chrome 的 cookies 是加密存储的,--cookies-from-browser chrome 可能失败并提示 "cannot decrypt v10 cookies"。此时必须使用扩展导出。
Cookies 文件格式
Cookies.txt 使用 Netscape 格式:
# Netscape HTTP Cookie File
# This file is generated by yt-dlp. Do not edit.
域名 标志 路径 安全标志 过期时间 名称 值示例:
.youtube.com TRUE / TRUE 1802063871 LOGIN_INFO AFmmF2swRQIhALvq...
.youtube.com TRUE / TRUE 1784781038 VISITOR_INFO1_LIVE KYjZnvuRYg8Cookies 文件位置
常见存放位置(按优先级):
- Near 全局搜索「引用至当前对话」:用户 @ 引用的 cookies 文件会以绝对路径注入
context_files(系统提示中的--- /path/to/file ---块)。直接使用该绝对路径,禁止对仅文件名做find/mdfind全局搜索。 - 浏览器扩展导出默认目录:macOS 常见为
~/Downloads/(如~/Downloads/www.youtube.com_cookies.txt) - 当前工作目录:
./cookies.txt - 项目目录:
/path/to/project/cookies.txt - 用户目录:
~/cookies.txt - 配置文件目录:
~/.config/yt-dlp/cookies.txt
路径解析规则(Near / Machi Desktop):
- 用户消息里可能显示
@cookies.txt · ~/Downloads,发送后会改写为@/Users/.../Downloads/cookies.txt - 执行
yt-dlp --cookies时必须使用context_files中的完整绝对路径,不要假设文件在当前 workspace 或项目根目录 - 若用户已 @ 引用 cookies 文件,不要再运行
find / -name ...或mdfind定位
网络和代理配置
代理检测和自动配置
使用代理检测脚本:
# 独立的代理检测工具
python3 .cursor/skills/yt-dlp-downloader/check_proxy.py使用安装脚本自动检测代理(包含代理检测):
python3 .cursor/skills/yt-dlp-downloader/install_yt_dlp.py安装脚本会自动检测:
- 环境变量中的代理配置(
HTTP_PROXY,HTTPS_PROXY,ALL_PROXY) - macOS 系统代理设置
- 本地常见代理端口(33210, 7890, 10808, 1080, 8080, 8888)
- 网络连接测试(测试是否能访问 YouTube)
Python 代码检测代理:
import os
import socket
import subprocess
import platform
def detect_proxy():
"""检测代理配置"""
proxy_info = {
"env_proxy": None,
"system_proxy": None,
"common_ports": [],
}
# 1. 检测环境变量
http_proxy = os.environ.get("HTTP_PROXY") or os.environ.get("http_proxy")
https_proxy = os.environ.get("HTTPS_PROXY") or os.environ.get("https_proxy")
all_proxy = os.environ.get("ALL_PROXY") or os.environ.get("all_proxy")
if http_proxy or https_proxy or all_proxy:
proxy_info["env_proxy"] = http_proxy or https_proxy or all_proxy
print(f"检测到环境变量代理: {proxy_info['env_proxy']}")
# 2. 检测 macOS 系统代理
if platform.system() == "Darwin":
try:
result = subprocess.run(
["networksetup", "-getwebproxy", "Wi-Fi"],
capture_output=True,
text=True,
timeout=2
)
if result.returncode == 0 and "Enabled: Yes" in result.stdout:
# 解析代理信息
lines = result.stdout.split("\n")
server = port = None
for line in lines:
if "Server:" in line:
server = line.split("Server:")[1].strip()
if "Port:" in line:
port = line.split("Port:")[1].strip()
if server and port:
proxy_info["system_proxy"] = f"http://{server}:{port}"
print(f"检测到系统代理: {proxy_info['system_proxy']}")
except:
pass
# 3. 检测常见代理端口
common_ports = [33210, 7890, 10808, 1080, 8080, 8888]
for port in common_ports:
try:
sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
sock.settimeout(0.5)
result = sock.connect_ex(("127.0.0.1", port))
sock.close()
if result == 0:
proxy_info["common_ports"].append(port)
except:
pass
if proxy_info["common_ports"]:
print(f"检测到本地代理端口: {proxy_info['common_ports']}")
return proxy_info
# 使用示例
proxy_info = detect_proxy()
if proxy_info["env_proxy"]:
proxy_url = proxy_info["env_proxy"]
elif proxy_info["system_proxy"]:
proxy_url = proxy_info["system_proxy"]
elif proxy_info["common_ports"]:
proxy_url = f"http://127.0.0.1:{proxy_info['common_ports'][0]}"
else:
proxy_url = NoneShell 脚本检测代理:
#!/bin/bash
# 检测环境变量代理
if [ -n "$HTTP_PROXY" ] || [ -n "$HTTPS_PROXY" ] || [ -n "$ALL_PROXY" ]; then
PROXY="${HTTP_PROXY:-${HTTPS_PROXY:-$ALL_PROXY}}"
echo "检测到环境变量代理: $PROXY"
fi
# 检测 macOS 系统代理
if [[ "$OSTYPE" == "darwin"* ]]; then
SYSTEM_PROXY=$(networksetup -getwebproxy Wi-Fi 2>/dev/null | grep "Server:" | awk '{print $2}')
SYSTEM_PORT=$(networksetup -getwebproxy Wi-Fi 2>/dev/null | grep "Port:" | awk '{print $2}')
if [ -n "$SYSTEM_PROXY" ] && [ -n "$SYSTEM_PORT" ]; then
echo "检测到系统代理: http://$SYSTEM_PROXY:$SYSTEM_PORT"
fi
fi
# 检测常见代理端口
COMMON_PORTS=(33210 7890 10808 1080 8080 8888)
for port in "${COMMON_PORTS[@]}"; do
if timeout 0.5 bash -c "echo > /dev/tcp/127.0.0.1/$port" 2>/dev/null; then
echo "检测到本地代理端口: $port"
fi
done代理设置
使用代理下载:
yt-dlp --proxy http://127.0.0.1:33210 --cookies cookies.txt <URL>代理类型:
- HTTP:
--proxy http://127.0.0.1:33210 - HTTPS:
--proxy https://127.0.0.1:33210 - SOCKS5:
--proxy socks5://127.0.0.1:1080
自动选择代理:
import subprocess
import os
def download_with_auto_proxy(url, cookies_file=None):
"""自动检测并使用代理下载"""
# 检测代理
proxy_url = None
# 1. 优先使用环境变量
proxy_url = os.environ.get("HTTP_PROXY") or os.environ.get("HTTPS_PROXY")
# 2. 如果没有,尝试常见端口
if not proxy_url:
common_ports = [33210, 7890, 10808, 1080]
for port in common_ports:
# 简单测试端口是否开放
try:
import socket
sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
sock.settimeout(0.5)
if sock.connect_ex(("127.0.0.1", port)) == 0:
proxy_url = f"http://127.0.0.1:{port}"
break
sock.close()
except:
continue
# 构建命令
cmd = ["yt-dlp"]
if proxy_url:
cmd.extend(["--proxy", proxy_url])
if cookies_file:
cmd.extend(["--cookies", cookies_file])
cmd.append(url)
# 执行下载
subprocess.run(cmd)macOS 系统代理配置
如果命令行工具无法直接连接代理,配置系统代理:
- 系统设置 → 网络 → Wi-Fi/Ethernet → 高级
- 代理标签页
- 配置 HTTP/HTTPS 代理:
- 服务器:
127.0.0.1 - 端口:
33210(或你的代理端口)
- 服务器:
- 保存后,yt-dlp 会自动使用系统代理
注意:配置系统代理后,所有应用都会使用代理,包括浏览器。如果只想让 yt-dlp 使用代理,建议使用 --proxy 参数。
配置文件方式
创建 ~/.config/yt-dlp/config 文件:
--proxy http://127.0.0.1:33210
--cookies /path/to/cookies.txt自动检测并写入配置文件:
import os
from pathlib import Path
def setup_yt_dlp_config(proxy_url=None, cookies_path=None):
"""设置 yt-dlp 配置文件"""
config_dir = Path.home() / ".config" / "yt-dlp"
config_dir.mkdir(parents=True, exist_ok=True)
config_file = config_dir / "config"
lines = []
if proxy_url:
lines.append(f"--proxy {proxy_url}")
if cookies_path:
lines.append(f"--cookies {cookies_path}")
if lines:
config_file.write_text("\n".join(lines))
print(f"配置文件已创建: {config_file}")
else:
print("无需创建配置文件")Error Handling
Common Issues
"yt-dlp: command not found"
- Install yt-dlp:
pip install yt-dlp或brew install yt-dlp - Check PATH if using binary
"Sign in to confirm you're not a bot"
- Use cookies:
yt-dlp --cookies cookies.txt <URL> - Export cookies using browser extension
"cannot decrypt v10 cookies" (macOS Chrome)
- macOS 上 Chrome cookies 是加密的,无法直接读取
- 解决方案:使用 "Get cookies.txt LOCALLY" 扩展导出 cookies.txt 文件
- 然后使用:
yt-dlp --cookies cookies.txt <URL>
"Failed to resolve 'www.youtube.com'"
- 网络连接问题,需要配置代理
- 排查步骤:
- 运行安装脚本检测代理:
python3 install_yt_dlp.py - 检查环境变量:
echo $HTTP_PROXY $HTTPS_PROXY - 检查代理服务是否运行(查看代理软件状态)
- 测试代理端口是否开放:
import socket sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM) result = sock.connect_ex(("127.0.0.1", 33210)) print("端口开放" if result == 0 else "端口关闭") - 配置系统代理或使用
--proxy参数 - 如果使用代理仍失败,尝试配置系统代理(macOS)
- 运行安装脚本检测代理:
"Operation not permitted" (代理连接失败)
- 代理服务可能只接受特定应用的连接
- 排查步骤:
- 检查代理服务是否允许命令行工具连接
- 尝试配置 macOS 系统代理(系统设置 → 网络 → 代理)
- 检查代理端口和类型是否正确:
# 测试 HTTP 代理 curl --proxy http://127.0.0.1:33210 https://www.google.com # 测试 SOCKS5 代理 curl --proxy socks5://127.0.0.1:1080 https://www.google.com - 如果代理需要认证,检查代理配置
- 解决方案:配置 macOS 系统代理(见上方),这样所有应用都会使用代理
代理检测和故障排除脚本:
import os
import socket
import subprocess
import platform
def diagnose_proxy_issues():
"""诊断代理问题"""
print("=" * 60)
print("代理诊断工具")
print("=" * 60)
# 1. 检查环境变量
print("\n1. 检查环境变量代理:")
http_proxy = os.environ.get("HTTP_PROXY") or os.environ.get("http_proxy")
https_proxy = os.environ.get("HTTPS_PROXY") or os.environ.get("https_proxy")
if http_proxy:
print(f" HTTP_PROXY: {http_proxy}")
if https_proxy:
print(f" HTTPS_PROXY: {https_proxy}")
if not http_proxy and not https_proxy:
print(" 未设置环境变量代理")
# 2. 检查 macOS 系统代理
if platform.system() == "Darwin":
print("\n2. 检查 macOS 系统代理:")
try:
result = subprocess.run(
["networksetup", "-getwebproxy", "Wi-Fi"],
capture_output=True,
text=True,
timeout=2
)
if "Enabled: Yes" in result.stdout:
print(" 系统代理已启用")
print(f" {result.stdout}")
else:
print(" 系统代理未启用")
except Exception as e:
print(f" 无法读取系统代理: {e}")
# 3. 检查常见代理端口
print("\n3. 检查本地代理端口:")
common_ports = [33210, 7890, 10808, 1080, 8080, 8888]
open_ports = []
for port in common_ports:
try:
sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
sock.settimeout(0.5)
result = sock.connect_ex(("127.0.0.1", port))
sock.close()
if result == 0:
open_ports.append(port)
print(f" 端口 {port}: ✓ 开放")
else:
print(f" 端口 {port}: ✗ 关闭")
except Exception as e:
print(f" 端口 {port}: ✗ 检查失败 ({e})")
# 4. 测试网络连接
print("\n4. 测试网络连接:")
try:
import urllib.request
urllib.request.urlopen("https://www.youtube.com", timeout=5)
print(" ✓ 可以直接访问 YouTube")
except Exception as e:
print(f" ✗ 无法直接访问 YouTube: {e}")
print(" 建议: 配置代理或使用 cookies")
# 5. 建议
print("\n5. 建议:")
if open_ports:
print(f" 检测到代理端口: {open_ports}")
print(f" 可以使用: yt-dlp --proxy http://127.0.0.1:{open_ports[0]} <URL>")
elif http_proxy or https_proxy:
print(" 环境变量已设置代理,yt-dlp 应该会自动使用")
else:
print(" 未检测到代理配置")
print(" 如果无法访问 YouTube,请:")
print(" 1. 配置代理: yt-dlp --proxy <proxy_url> <URL>")
print(" 2. 配置系统代理(macOS: 系统设置 → 网络 → 代理)")
print(" 3. 使用 cookies: yt-dlp --cookies cookies.txt <URL>")
if __name__ == "__main__":
diagnose_proxy_issues()"No video formats found"
- Check if video is available
- Try with cookies if login required
- Check if site is supported:
yt-dlp --list-extractors
Slow download speed
- Use concurrent fragments:
yt-dlp --concurrent-fragments 8 <URL> - Use external downloader:
yt-dlp --downloader aria2c <URL>
Workflow
When user provides a video URL:
- Detect the URL - Identify if it's a video URL from supported sites
- 检测环境并检查安装
- 检测操作系统(macOS/Linux/Windows)
- 检测 Python 和包管理器(pip/pip3/brew/apt-get)
- 检查 yt-dlp 是否已安装:
yt-dlp --version - 如果未安装,根据环境自动安装:
- macOS/Linux:
pip3 install yt-dlp或pip install yt-dlp - macOS (可选):
brew install yt-dlp
- macOS/Linux:
- (可选)检查 FFmpeg:
ffmpeg -version
- 检测网络和代理配置
- 检测环境变量中的代理(
HTTP_PROXY,HTTPS_PROXY,ALL_PROXY) - 检测 macOS 系统代理设置(如果适用)
- 检测本地常见代理端口(33210, 7890, 10808, 1080, 8080, 8888)
- 测试网络连接(测试是否能访问 YouTube)
- 若用户已 @ 引用 cookies 或系统提示
context_files含绝对路径,直接使用该路径;否则再按「Cookies 文件位置」节查找(含~/Downloads/,禁止全局find/mdfind) - 根据检测结果自动选择代理配置
- 检测环境变量中的代理(
- Determine user intent:
- Video only? → Use default format
- Audio only? → Use
-x --audio-format mp3 - Specific quality? → List formats first with
-F - With subtitles? → Add
--write-subs
- Execute download - Run appropriate yt-dlp command
- 基本下载:
yt-dlp <URL> - 如果需要 cookies:
yt-dlp --cookies cookies.txt <URL> - 如果需要代理:
yt-dlp --proxy <proxy_url> --cookies cookies.txt <URL> - If network error → Try with cookies:
yt-dlp --cookies cookies.txt <URL> - If still fails → Check proxy configuration
- 基本下载:
- Handle errors - Provide helpful error messages and solutions
- 如果安装失败,提供环境检测和安装脚本
- 如果网络失败,提示配置代理或 cookies
- 如果下载失败,提供错误排查建议
调试经验和最佳实践
成功案例:YouTube 视频下载
场景:macOS 环境,需要代理和 cookies
步骤:
- 安装 yt-dlp:
brew install yt-dlp - 导出 cookies:
- 安装 "Get cookies.txt LOCALLY" 扩展
- 在 YouTube 页面导出 cookies
- 保存为
cookies.txt
- 配置系统代理(如果代理无法直接连接)
- 下载视频:
yt-dlp --cookies cookies.txt "https://www.youtube.com/watch?v=XXX"
关键点:
- macOS 上 Chrome cookies 无法直接读取,必须使用扩展导出
- 如果代理连接失败,配置系统代理更可靠
- Cookies 文件格式必须正确(Netscape 格式)
常见问题排查流程
- 检查安装:
yt-dlp --version - 测试网络连接:
curl -I https://www.youtube.com - 如果网络失败,尝试 cookies:
yt-dlp --cookies cookies.txt <URL> - 如果 cookies 失败,检查文件格式:
- 确保是 Netscape 格式
- 检查文件路径是否正确
- 确保 cookies 未过期
- 如果代理失败:
- 检查代理服务是否运行
- 尝试配置系统代理
- 检查代理端口和类型
最佳实践
- Cookies 管理:
- 定期更新 cookies(通常有效期较长)
- 将 cookies.txt 放在项目目录便于管理
- 不要将 cookies.txt 提交到 Git(添加到 .gitignore)
- 代理配置:
- 优先使用系统代理(更稳定)
- 如果必须使用命令行代理,确保代理服务支持命令行工具
- 记录代理配置到配置文件
- 下载选项:
- 使用
--merge-output-format mp4确保输出格式 - 使用
-o指定输出路径和文件名模板 - 使用
--write-subs同时下载字幕
- 使用
- 错误处理:
- 遇到错误先检查网络和 cookies
- 查看详细错误信息:
yt-dlp -v <URL> - 记录成功配置以便复用
Examples
Example 1: Simple download
User: "下载这个视频 https://www.youtube.com/watch?v=xxx"
→ yt-dlp https://www.youtube.com/watch?v=xxxExample 2: Audio only
User: "提取这个视频的音频 https://www.youtube.com/watch?v=xxx"
→ yt-dlp -x --audio-format mp3 https://www.youtube.com/watch?v=xxxExample 3: With subtitles
User: "下载这个视频和字幕 https://www.youtube.com/watch?v=xxx"
→ yt-dlp --write-subs --sub-langs zh-Hans https://www.youtube.com/watch?v=xxxExample 4: Specific quality
User: "下载1080p版本 https://www.youtube.com/watch?v=xxx"
→ yt-dlp -f "bestvideo[height<=1080]+bestaudio/best[height<=1080]" https://www.youtube.com/watch?v=xxxExample 5: With cookies (most common for YouTube)
User: "下载这个视频 https://www.youtube.com/watch?v=xxx"
→ yt-dlp --cookies cookies.txt "https://www.youtube.com/watch?v=xxx"Example 6: With proxy and cookies
User: "下载这个视频 https://www.youtube.com/watch?v=xxx" (需要代理)
→ yt-dlp --proxy http://127.0.0.1:33210 --cookies cookies.txt "https://www.youtube.com/watch?v=xxx"实际调试案例
案例:macOS 下载 YouTube 视频
问题:
- 网络连接失败:"Failed to resolve 'www.youtube.com'"
- Chrome cookies 无法读取:"cannot decrypt v10 cookies"
解决步骤:
- 安装 "Get cookies.txt LOCALLY" 扩展
- 在 YouTube 页面导出 cookies 为 cookies.txt
- 配置 macOS 系统代理(如果代理无法直接连接)
- 使用 cookies 下载:
yt-dlp --cookies cookies.txt "https://www.youtube.com/watch?v=XXX"
成功输出示例:
[youtube] Extracting URL: https://www.youtube.com/watch?v=XXX
[youtube] XXX: Downloading webpage
[youtube] [jsc:deno] Solving JS challenges using deno
[youtube] XXX: Downloading m3u8 information
[info] XXX: Downloading 1 format(s): 399+251
[download] Destination: video_title [XXX].f399.mp4
[download] 100% of 17.85MiB in 00:00:03 at 4.67MiB/s
[download] Destination: video_title [XXX].f251.webm
[download] 100% of 1.31MiB in 00:00:00 at 3.85MiB/s
[Merger] Merging formats into "video_title [XXX].webm"关键要点:
- Cookies.txt 文件格式必须正确(Netscape 格式)
- macOS 上必须使用扩展导出 cookies
- 系统代理配置比命令行代理更可靠
- yt-dlp 会自动使用 deno 解决 JS challenges
快速参考
最常用命令
基本下载(使用 cookies):
yt-dlp --cookies cookies.txt "https://www.youtube.com/watch?v=XXX"下载并转换为 MP4:
yt-dlp --cookies cookies.txt --merge-output-format mp4 "https://www.youtube.com/watch?v=XXX"下载音频为 MP3:
yt-dlp --cookies cookies.txt -x --audio-format mp3 "https://www.youtube.com/watch?v=XXX"下载视频和字幕:
yt-dlp --cookies cookies.txt --write-subs --sub-langs zh-Hans "https://www.youtube.com/watch?v=XXX"使用代理和 cookies:
yt-dlp --proxy http://127.0.0.1:33210 --cookies cookies.txt "https://www.youtube.com/watch?v=XXX"Cookies 文件位置
默认查找位置(按优先级):
- Near 对话 @ 引用 / context_files 绝对路径(最高优先级,禁止全局 find)
- macOS 浏览器扩展导出:
~/Downloads/(如www.youtube.com_cookies.txt) - 当前目录:
./cookies.txt - 项目目录:
/path/to/project/cookies.txt - 用户目录:
~/cookies.txt - 配置文件目录:
~/.config/yt-dlp/cookies.txt
配置文件位置
- macOS/Linux:
~/.config/yt-dlp/config - Windows:
%APPDATA%/yt-dlp/config
配置文件示例:
--proxy http://127.0.0.1:33210
--cookies cookies.txt
--merge-output-format mp4
-o ~/Downloads/%(title)s.%(ext)sDoes it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

