← 返回首页

yt-dlp 安装使用说明

2026-10-26 · 元 / yokon

Windows 本机用 Python 安装 yt-dlp：基础下载、格式选择、可选代理与 cookies，以及常见排错。

下载 PDF 版

工具：yt-dlp（youtube-dl 的活跃分支）
上游：https://github.com/yt-dlp/yt-dlp
整理日期：2026-10-26（Asia/Shanghai）

简介

yt-dlp 是一个命令行视频下载工具，由 youtube-dl 社区 fork 并持续维护。它支持 YouTube 以及大量其它站点，适合把你有权保存的内容下载到本机做离线观看或个人备份。

本说明以 Windows + Python pip 安装 为主，命令在 PowerShell 或「命令提示符」中运行均可。

使用提醒：请只下载你有权使用的内容（例如自己的作品、已获授权、或平台明确允许的个人备份）。请遵守当地法律法规与各站点服务条款；本文不鼓励侵犯版权。

Windows 安装

1. 准备 Python

安装 Python 3.10+（推荐 3.12 / 3.13）。
安装时勾选 Add python.exe to PATH。
新开一个终端验证：

python --version
# 应显示 3.10 或更高

2. 安装 / 升级 yt-dlp

python -m pip install -U yt-dlp

验证版本：

yt-dlp --version
# 例如：2026.10.21（以你本机实际输出为准）

若提示找不到 yt-dlp，可改用：

python -m yt_dlp --version

并把 Python 的 Scripts 目录加入 PATH（安装 Python 时勾选 PATH 通常已足够）。

3. 可选：ffmpeg（合并音视频）

很多站点会把视频轨与音频轨分开。要得到「带声音的完整文件」，建议安装 ffmpeg，并确保 ffmpeg 能在终端里直接调用：

ffmpeg -version

4. 可选进阶：deno（部分 YouTube 提取）

少数场景下，上游会建议配合 JS 运行时（如 deno）做更完整的提取，例如：

yt-dlp --js-runtimes deno --remote-components ejs:github "URL"

这是可选进阶用法；日常下载多数时候不需要。需要时再按 yt-dlp 文档安装 deno 即可。

基本用法

直接下载

yt-dlp "https://www.youtube.com/watch?v=视频ID"

把引号里的地址换成你的目标链接。

指定输出文件名 / 目录

yt-dlp -o "%USERPROFILE%\Downloads\%(title)s [%(id)s].%(ext)s" "URL"

常用模板字段：%(title)s 标题、%(id)s 视频 ID、%(ext)s 扩展名、%(uploader)s 上传者。

查看可用格式

yt-dlp -F "URL"

按列表里的编号选用，例如：

yt-dlp -f 137+140 "URL"

默认「尽量最好」的视频 + 音频

不指定 -f 时，yt-dlp 会尽量选较好画质并合并（有 ffmpeg 时更稳）：

yt-dlp -f "bv*+ba/b" "URL"

可选：本机代理

若目标站点在你所在网络无法直连，可让 yt-dlp 走本机代理客户端（Clash / v2rayN / 其它本地 socks 端口均可）。

把下面的 PORT 改成你本机代理软件界面上显示的本地端口（不要照抄别人的端口号）：

yt-dlp --proxy socks5://127.0.0.1:PORT "URL"

示例（仅作格式参考，端口请按本机修改）：

yt-dlp --proxy socks5://127.0.0.1:10808 "URL"

也可用 http://127.0.0.1:PORT，取决于你的客户端提供的是 HTTP 还是 SOCKS 入口。

可选：浏览器 cookies

部分视频需要登录态（年龄限制、会员内容、地区限制等）。常见做法是从浏览器导出 cookies 到文本文件，再交给 yt-dlp。

用浏览器扩展或导出工具，把站点 cookies 存成 Netscape 格式的 cookies.txt。
建议放在下载目录，例如：

%USERPROFILE%\Downloads\youtube-cookies.txt

下载时加上：

yt-dlp --cookies "%USERPROFILE%\Downloads\youtube-cookies.txt" "URL"

也可与代理一起用：

yt-dlp --proxy socks5://127.0.0.1:PORT --cookies "%USERPROFILE%\Downloads\youtube-cookies.txt" "URL"

安全提醒（重要）：

cookies 文件等同于登录凭证，不要分享、不要发到群聊 / 公开帖子。
不要提交到 Git，不要放进会同步到公开仓库的目录。
本文只给路径占位与示例文件名；请用你自己导出的文件，过期后重新导出即可。

常用示例

单个视频

yt-dlp "URL"

播放列表

yt-dlp -o "%USERPROFILE%\Downloads\%(playlist_title)s\%(playlist_index)03d - %(title)s.%(ext)s" "播放列表URL"

只要音频（如转 mp3）

需要本机已装 ffmpeg：

yt-dlp -x --audio-format mp3 "URL"

下载字幕

yt-dlp --write-subs --sub-langs "zh-Hans,zh-Hant,en" --skip-download "URL"

若只要内嵌/自动字幕，可再查文档中的 --write-auto-subs 等选项。边下视频边下字幕可去掉 --skip-download。

限制下载速率（可选）

yt-dlp -r 5M "URL"

常见问题

现象	可能原因 / 处理
报错 / 解析失败	先升级：`python -m pip install -U yt-dlp`，再重试
年龄限制 / 需要登录	导出浏览器 cookies，加 `--cookies`（见上文）
地区无法播放	开启本机代理，加 `--proxy socks5://127.0.0.1:PORT`（端口改成你的）
有画面没声音 / 格式奇怪	安装 ffmpeg，并用 `bv*+ba/b` 或 `-F` 手动选轨合并
找不到 `yt-dlp` 命令	用 `python -m yt_dlp ...`，或检查 Python `Scripts` 是否在 PATH
cookies 突然失效	重新从浏览器导出；不要用过期或别人分享的 cookies 文件