输出文件名模板

通过 -o 参数（或 Python 的 outtmpl），你可以完全控制下载文件的名称和存放路径。

基础语法

模板使用 %(字段名)s 的格式（Python 字符串格式化语法）。

# 使用视频标题作为文件名（默认行为）
yt-dlp -o "%(title)s.%(ext)s" "URL"

# 自定义路径
yt-dlp -o "~/Music/%(title)s.%(ext)s" "URL"

# 包含上传者名称
yt-dlp -o "%(uploader)s - %(title)s.%(ext)s" "URL"

# 按上传者分类存放
yt-dlp -o "%(uploader)s/%(title)s.%(ext)s" "URL"

import yt_dlp

ydl_opts = {
    'outtmpl': '%(uploader)s/%(title)s.%(ext)s',
}

with yt_dlp.YoutubeDL(ydl_opts) as ydl:
    ydl.download(["URL"])

常用模板变量

变量	说明	示例值
`%(title)s`	视频标题	`我的视频`
`%(ext)s`	文件扩展名	`mp4`
`%(id)s`	视频 ID	`BV1xx411c7mD`
`%(uploader)s`	上传者名称	`ExampleUser`
`%(uploader_id)s`	上传者 ID	`UC1234`
`%(upload_date)s`	上传日期	`20240101`
`%(duration)s`	视频时长（秒）	`180`
`%(view_count)s`	播放量	`12345`
`%(like_count)s`	点赞数	`678`
`%(resolution)s`	分辨率	`1920x1080`
`%(fps)s`	帧率	`30`
`%(channel)s`	频道名	`我的频道`
`%(playlist_title)s`	播放列表标题	`收藏夹`
`%(playlist_index)s`	播放列表序号	`1`
`%(webpage_url)s`	原始页面 URL	`https://...`

高级模板技巧

日期格式化

# 日期格式化为 YYYY-MM-DD
yt-dlp -o "%(upload_date>%Y-%m-%d)s - %(title)s.%(ext)s" "URL"
# 输出: 2024-01-15 - 我的视频.mp4

截断长标题

# 标题最多 50 个字符
yt-dlp -o "%(title).50s.%(ext)s" "URL"

播放列表编号补零

# 序号补零（3位，如 001、002）
yt-dlp -o "%(playlist_index)03d - %(title)s.%(ext)s" "URL"

条件模板

# 根据是否是播放列表使用不同模板
yt-dlp -o "%(playlist_title)s/%(playlist_index)03d - %(title)s.%(ext)s" "PLAYLIST_URL"

实用模板推荐

# 音乐下载：艺术家/歌曲名
yt-dlp -o "%(uploader)s/%(title)s.%(ext)s" -x --audio-format m4a "URL"

# 视频归档：日期_标题_ID
yt-dlp -o "%(upload_date)s_%(title).50s_%(id)s.%(ext)s" "URL"

# 播放列表：列表名/序号_标题
yt-dlp -o "%(playlist_title)s/%(playlist_index)03d_%(title)s.%(ext)s" "URL"

# 频道完整备份
yt-dlp -o "%(channel)s/%(upload_date>%Y-%m-%d)s - %(title)s [%(id)s].%(ext)s" "URL"

import yt_dlp

# 音乐下载模板
music_opts = {
    'outtmpl': '%(uploader)s/%(title)s.%(ext)s',
    'format': 'bestaudio/best',
    'postprocessors': [{
        'key': 'FFmpegExtractAudio',
        'preferredcodec': 'm4a',
        'preferredquality': '0',
    }],
}

# 视频归档模板
archive_opts = {
    'outtmpl': '%(upload_date)s_%(title).50s_%(id)s.%(ext)s',
}

with yt_dlp.YoutubeDL(music_opts) as ydl:
    ydl.download(["URL"])

更多模板变量参见输出模板变量参考。

输出文件名模板

On this page