Back to Details

yt-dlp-downloader

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

yt-dlp Video Downloader

yt-dlp 视频下载工具

Download videos from thousands of websites using yt-dlp.
使用yt-dlp从数千个网站下载视频。

Prerequisites

前提条件

Before downloading, verify dependencies are installed:
bash
undefined
下载前，请确认已安装以下依赖项：
bash
undefined

Check yt-dlp

Check yt-dlp

which yt-dlp || echo "yt-dlp not installed. Install with: pip install yt-dlp"
which yt-dlp || echo "yt-dlp not installed. Install with: pip install yt-dlp"

Check ffmpeg (required for audio extraction and format merging)

Check ffmpeg (required for audio extraction and format merging)

which ffmpeg || echo "ffmpeg not installed. Install with: brew install ffmpeg"

If not installed, install them first:
```bash
pip install yt-dlp
brew install ffmpeg  # macOS
which ffmpeg || echo "ffmpeg not installed. Install with: brew install ffmpeg"

如果未安装，请先执行以下命令安装：
```bash
pip install yt-dlp
brew install ffmpeg  # macOS

Quick Start

快速开始

Basic Download (Best Quality)

基础下载（最佳画质）

bash
yt-dlp -P "~/Downloads/yt-dlp" "VIDEO_URL"
bash
yt-dlp -P "~/Downloads/yt-dlp" "VIDEO_URL"

YouTube Download (Recommended - with cookies)

YouTube 下载（推荐 - 使用Cookie）

YouTube often blocks direct downloads with 403 errors. Always use browser cookies for YouTube:
bash
yt-dlp -P "~/Downloads/yt-dlp" --cookies-from-browser chrome "YOUTUBE_URL"
Supported browsers: 
chrome
, 
firefox
, 
safari
, 
edge
, 
brave
, 
opera
YouTube 经常会返回403错误阻止直接下载，请务必使用浏览器Cookie进行YouTube下载：
bash
yt-dlp -P "~/Downloads/yt-dlp" --cookies-from-browser chrome "YOUTUBE_URL"
支持的浏览器：
chrome
, 
firefox
, 
safari
, 
edge
, 
brave
, 
opera

Download with Custom Output Path

自定义输出路径下载

bash
yt-dlp -P "/path/to/save" -o "%(title)s.%(ext)s" "VIDEO_URL"
bash
yt-dlp -P "/path/to/save" -o "%(title)s.%(ext)s" "VIDEO_URL"

Common Tasks

常见操作

1. Download Video (Default - Best Quality)

1. 下载视频（默认 - 最佳画质）

bash
yt-dlp -P "~/Downloads/yt-dlp" "VIDEO_URL"
bash
yt-dlp -P "~/Downloads/yt-dlp" "VIDEO_URL"

2. Extract Audio Only (MP3)

2. 仅提取音频（MP3格式）

bash
yt-dlp -P "~/Downloads/yt-dlp" -x --audio-format mp3 "VIDEO_URL"
bash
yt-dlp -P "~/Downloads/yt-dlp" -x --audio-format mp3 "VIDEO_URL"

3. Download with Subtitles

3. 下载带字幕的视频

bash
yt-dlp -P "~/Downloads/yt-dlp" --write-subs --sub-langs all "VIDEO_URL"
bash
yt-dlp -P "~/Downloads/yt-dlp" --write-subs --sub-langs all "VIDEO_URL"

4. Download Specific Quality

4. 下载指定画质的视频

720p:
bash
yt-dlp -P "~/Downloads/yt-dlp" -f "bestvideo[height<=720]+bestaudio/best[height<=720]" "VIDEO_URL"
1080p:
bash
yt-dlp -P "~/Downloads/yt-dlp" -f "bestvideo[height<=1080]+bestaudio/best[height<=1080]" "VIDEO_URL"
Best available:
bash
yt-dlp -P "~/Downloads/yt-dlp" -f "bestvideo+bestaudio/best" "VIDEO_URL"
720p：
bash
yt-dlp -P "~/Downloads/yt-dlp" -f "bestvideo[height<=720]+bestaudio/best[height<=720]" "VIDEO_URL"
1080p：
bash
yt-dlp -P "~/Downloads/yt-dlp" -f "bestvideo[height<=1080]+bestaudio/best[height<=1080]" "VIDEO_URL"
可用最佳画质：
bash
yt-dlp -P "~/Downloads/yt-dlp" -f "bestvideo+bestaudio/best" "VIDEO_URL"

5. List Available Formats (Before Download)

5. 查看可用格式（下载前）

bash
yt-dlp -F "VIDEO_URL"
Then download specific format by ID:
bash
yt-dlp -P "~/Downloads/yt-dlp" -f FORMAT_ID "VIDEO_URL"
bash
yt-dlp -F "VIDEO_URL"
然后通过格式ID下载指定格式：
bash
yt-dlp -P "~/Downloads/yt-dlp" -f FORMAT_ID "VIDEO_URL"

6. Download Playlist

6. 下载播放列表

bash
undefined
bash
undefined

Download entire playlist

Download entire playlist

yt-dlp -P "~/Downloads/yt-dlp" -o "%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s" "PLAYLIST_URL"
yt-dlp -P "~/Downloads/yt-dlp" -o "%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s" "PLAYLIST_URL"

Download specific range (e.g., items 1-5)

Download specific range (e.g., items 1-5)

yt-dlp -P "~/Downloads/yt-dlp" -I 1:5 "PLAYLIST_URL"
undefined
yt-dlp -P "~/Downloads/yt-dlp" -I 1:5 "PLAYLIST_URL"
undefined

7. Download with Thumbnail

7. 下载视频及缩略图

bash
yt-dlp -P "~/Downloads/yt-dlp" --write-thumbnail "VIDEO_URL"
bash
yt-dlp -P "~/Downloads/yt-dlp" --write-thumbnail "VIDEO_URL"

Workflow

操作流程

When user provides a video URL:
  1. Identify the platform:
    • YouTube/YouTube Music → Always use 
      --cookies-from-browser chrome
    • Other sites → Try without cookies first
  2. Ask what they want (if not specified):
    • Just download the video?
    • Extract audio only?
    • Need subtitles?
    • Specific quality?
  3. Construct the command based on requirements
  4. Execute the download using Shell tool with 
    required_permissions: ["all", "network"]
  5. Handle errors:
    • 403 Forbidden → Retry with 
      --cookies-from-browser
    • Connection issues → yt-dlp auto-resumes, just retry
    • Format unavailable → Use 
      -F
      to list formats, then select
  6. Report the result - file location and any errors
当用户提供视频URL时：
  1. 识别平台：
    • YouTube/YouTube Music → 请始终使用 
      --cookies-from-browser chrome
      参数
    • 其他网站 → 先尝试不使用Cookie下载
  2. 确认需求（如果用户未明确说明）：
    • 仅下载视频？
    • 仅提取音频？
    • 是否需要字幕？
    • 指定画质？
  3. 根据需求构造命令
  4. 使用Shell工具执行下载，需申请权限：
    required_permissions: ["all", "network"]
  5. 错误处理：
    • 403 禁止访问 → 使用 
      --cookies-from-browser
      参数重试
    • 连接问题 → yt-dlp支持自动续传，直接重试即可
    • 格式不可用 → 使用 
      -F
      查看可用格式后再选择
  6. 反馈结果 - 告知文件保存位置及任何错误信息

Example Interaction

交互示例

User: "帮我下载这个视频 https://www.youtube.com/watch?v=xxx"
Response:
bash
undefined
用户："帮我下载这个视频 https://www.youtube.com/watch?v=xxx"
响应：
bash
undefined

YouTube - use cookies to avoid 403 errors

YouTube - use cookies to avoid 403 errors

yt-dlp -P "~/Downloads/yt-dlp" --cookies-from-browser chrome "https://www.youtube.com/watch?v=xxx"

User: "下载这个视频的音频 https://www.bilibili.com/video/xxx"

Response:
```bash
yt-dlp -P "~/Downloads/yt-dlp" --cookies-from-browser chrome "https://www.youtube.com/watch?v=xxx"

用户："下载这个视频的音频 https://www.bilibili.com/video/xxx"

响应：
```bash

Bilibili - extracting audio as MP3

Bilibili - extracting audio as MP3

yt-dlp -P "~/Downloads/yt-dlp" -x --audio-format mp3 "https://www.bilibili.com/video/xxx"

User: "下载这个 Twitter 视频 https://twitter.com/xxx/status/123"

Response:
```bash
yt-dlp -P "~/Downloads/yt-dlp" -x --audio-format mp3 "https://www.bilibili.com/video/xxx"

用户："下载这个 Twitter 视频 https://twitter.com/xxx/status/123"

响应：
```bash

Twitter/X - direct download usually works

Twitter/X - direct download usually works

yt-dlp -P "~/Downloads/yt-dlp" "https://twitter.com/xxx/status/123"
undefined
yt-dlp -P "~/Downloads/yt-dlp" "https://twitter.com/xxx/status/123"
undefined

Supported Sites

支持的网站

yt-dlp supports thousands of sites including:
  • YouTube, YouTube Music
  • Bilibili (B站)
  • Twitter/X
  • TikTok, Douyin (抖音)
  • Vimeo
  • Twitch
  • And many more...
Full list: https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md
yt-dlp 支持数千个网站，包括：
  • YouTube、YouTube Music
  • Bilibili（B站）
  • Twitter/X
  • TikTok、Douyin（抖音）
  • Vimeo
  • Twitch
  • 以及更多...
完整列表：https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md

Troubleshooting

故障排除

Common Errors and Solutions

常见错误及解决方法

ErrorCauseSolution
HTTP 403 ForbiddenYouTube blocks unauthenticated requestsUse 
--cookies-from-browser chrome
Video unavailableGeo-restricted or privateUse cookies or VPN
Download interruptedNetwork issuesRetry - yt-dlp auto-resumes
Format not availableRequested format doesn't existUse 
-F
to list formats
错误原因解决方法
HTTP 403 ForbiddenYouTube 阻止未授权请求使用 
--cookies-from-browser chrome
参数
Video unavailable视频受地区限制或为私有视频使用Cookie或VPN
Download interrupted网络问题重试 - yt-dlp支持自动续传
Format not available请求的格式不存在使用 
-F
查看可用格式

Error: "yt-dlp: command not found"

错误："yt-dlp: command not found"

bash
pip install yt-dlp
bash
pip install yt-dlp

Error: "ffmpeg not found" (for audio extraction)

错误："ffmpeg not found"（提取音频时）

bash
brew install ffmpeg  # macOS
bash
brew install ffmpeg  # macOS

Error: HTTP 403 Forbidden (YouTube)

错误：HTTP 403 Forbidden（YouTube）

This is the most common YouTube error. Always use cookies for YouTube:
bash
undefined
这是YouTube最常见的错误。请始终使用Cookie进行YouTube下载：
bash
undefined

Recommended approach for YouTube

Recommended approach for YouTube

yt-dlp -P "~/Downloads/yt-dlp" --cookies-from-browser chrome "YOUTUBE_URL"

Supported browsers: `chrome`, `firefox`, `safari`, `edge`, `brave`, `opera`
yt-dlp -P "~/Downloads/yt-dlp" --cookies-from-browser chrome "YOUTUBE_URL"

支持的浏览器：`chrome`, `firefox`, `safari`, `edge`, `brave`, `opera`

Error: Video unavailable or geo-restricted

错误：视频不可用或受地区限制

bash
undefined
bash
undefined

Try with cookies from browser

Try with cookies from browser

yt-dlp --cookies-from-browser chrome "VIDEO_URL"
yt-dlp --cookies-from-browser chrome "VIDEO_URL"

Or use a specific format

Or use a specific format

yt-dlp -F "VIDEO_URL" # List formats first yt-dlp -f FORMAT_ID "VIDEO_URL"
undefined
yt-dlp -F "VIDEO_URL" # List formats first yt-dlp -f FORMAT_ID "VIDEO_URL"
undefined

Error: Download keeps failing

错误：下载持续失败

bash
undefined
bash
undefined

Update yt-dlp to latest version

Update yt-dlp to latest version

pip install -U yt-dlp
pip install -U yt-dlp

Force IPv4 (sometimes helps with connection issues)

Force IPv4 (sometimes helps with connection issues)

yt-dlp -4 "VIDEO_URL"
undefined
yt-dlp -4 "VIDEO_URL"
undefined

Best Practices

最佳实践

  1. YouTube downloads: Always use 
    --cookies-from-browser chrome
  2. Large files: yt-dlp auto-resumes, just retry if interrupted
  3. Keep yt-dlp updated: 
    pip install -U yt-dlp
  4. Check formats first: Use 
    -F
    before downloading if unsure
  1. YouTube 下载：请始终使用 
    --cookies-from-browser chrome
    参数
  2. 大文件下载：yt-dlp支持自动续传，中断后直接重试即可
  3. 保持yt-dlp更新：执行 
    pip install -U yt-dlp
    命令更新
  4. 先查看格式：若不确定可用格式，下载前使用 
    -F
    命令查看