spotDL v4 完全指南将 Spotify 歌单、专辑与歌曲下载到本地的 CLI 工具【免费下载链接】spotify-downloaderDownload your Spotify playlists and songs along with album art and metadata (from YouTube if a match is found).项目地址: https://gitcode.com/GitHub_Trending/sp/spotify-downloaderspotDL 是一款基于 Python 的命令行音乐下载器其核心工作方式是从 Spotify 获取歌曲/歌单/专辑/艺术家的元数据曲名、艺术家、专辑封面、歌词等再到 YouTube或 SoundCloud、Bandcamp 等备选来源上匹配并下载对应的音频最后把完整元数据嵌入本地文件。读完本文你将掌握 spotDL 的安装与依赖配置、download/save/web/url/sync/meta六大操作的使用方法、音频格式与码率策略以及配置文件与模板变量的完整语义并能结合仓库源码理解其底层实现。项目概览spotDL v4 是当前仓库的主线版本。用官方的一句话概括spotDL 从 Spotify 歌单中寻找歌曲并在 YouTube 上完成下载——同时附带专辑封面、歌词和元数据。它避免了直接抓取 Spotify 音频的合规风险改为Spotify 提供元数据、YouTube 提供音频流的间接方案因此被称为最快、最简单、最准确的命令行音乐下载器该描述来自项目官方 README属于项目自身的定位表述。从仓库结构可以清晰看出它的分层设计见 spotdl/ 目录spotdl/console/命令行入口与各操作download、save、sync、meta、url、web的实现spotdl/download/核心下载器Downloader与进度处理spotdl/providers/音频来源youtube、youtube-music、soundcloud、bandcamp、piped、sliderkz与歌词来源genius、azlyrics、musixmatch、synced的插件式实现spotdl/types/Song、Album、Artist、Playlist、Saved 等数据模型spotdl/utils/参数解析、配置、搜索、元数据嵌入、ffmpeg 封装等工具。该项目的依赖与 Python 版本要求在 pyproject.toml 中声明requires-python 3.10,3.15核心依赖包括spotipy/spotipyFreeSpotify API 客户端、ytmusicapi、yt-dlpYouTube 下载引擎、mutagen音频标签、rapidfuzz模糊匹配、syncedlyrics同步歌词、fastapiuvicornWeb UI等安装后会自动提供spotdl命令[project.scripts] spotdl spotdl:console_entry_point。安装指南Python 方式推荐spotDL 已发布到 PyPI最简单的安装方式pip install spotdl更新到最新版本pip install --upgrade spotdl在某些系统上可能需要把pip换成pip3macOS/Linux 环境下同理Python 命令也可换成python3。更完整的安装步骤见 docs/installation.md安装前需确保系统具备 Python 3.10–3.14 且已加入 PATHWindows 安装器务必勾选 Add to PATH见 docs/images/ADD_TO_PATH.pngWindows 用户还需要安装 Visual C 2019 Redistributable。其他安装方式预构建可执行文件从 Releases 页面下载最新版本的可执行文件无参数运行时默认启动 Web UI带参数时走 CLI./spotdl-vX.X.X operation [urls]TermuxAndroid一行脚本安装scripts/termux.shcurl -L https://raw.githubusercontent.com/spotDL/spotify-downloader/master/scripts/termux.sh | sh该脚本位于仓库 scripts/termux.shArch LinuxAUR存在官方 AUR 包spotdl可直接通过 AUR 辅助工具安装Docker仓库自带 Dockerfile 与 docker-compose.yml。构建镜像并运行docker build -t spotdl . docker run --rm -v $(pwd):/music spotdl download [trackUrl]绑定挂载的宿主机目录需要保证容器内 UID/GID 可写也可直接拉取 Docker Hub 镜像spotdl/spotify-downloader使用或借助 Docker Compose 让 Docker 代为管理权限设置PUID/PGID环境变量详见 docs/installation.md从源码构建克隆仓库后使用 uv 同步依赖并构建可执行文件git clone https://gitcode.com/GitHub_Trending/sp/spotify-downloader cd spotify-downloader pip install uv uv sync uv run scripts/build.py构建产物会输出到spotify-downloader/dist/。安装 FFmpeg必需FFmpeg 是 spotDL 的硬性依赖用于音频格式转换与元数据嵌入。如果 FFmpeg 仅服务于 spotDL官方建议直接安装到 spotDL 目录spotdl --download-ffmpeg也可以系统级安装macOS 使用brew install ffmpegLinux 使用sudo apt install ffmpeg或其他发行版包管理器。文档要求 FFmpeg 4.2 及以上版本并加入 PATH。从源码看FFmpeg 的检查是启动流程的一部分spotdl/console/entry_point.py 中在解析参数后调用is_ffmpeg_installed()若未安装会直接抛出FFmpegError并提示运行spotdl --download-ffmpeg或使用--ffmpeg /path/to/ffmpeg指定路径Downloader初始化时若配置的 ffmpeg 为默认值且系统 PATH 中找不到还会自动回退到 spotdl 目录下的 ffmpeg。安装 Deno强烈推荐spotDL 的 YouTube 下载基于 yt-dlp而部分视频包括标记为 made for kids 的视频需要 Deno 运行时才能成功下载。缺少 Deno 时某些歌曲可能会下载失败。与 FFmpeg 一样仅用于 spotDL 时可直接安装到 spotDL 目录spotdl --download-deno快速上手基本用法不带任何选项直接运行等价于执行默认的download操作spotdl [urls]如果脚本方式无法运行可以以包方式调用python -m spotdl [urls]通用语法为spotdl [operation] [options] QUERY其中operation是六大操作之一缺省为downloadQUERY通常是若干 Spotify URL某些操作如sync只需要单个链接或文件。所有选项可用spotdl -h查看完整帮助。小提示spotDL 下载的文件默认保存在运行命令时所在的当前目录因此可以先cd到目标文件夹再执行命令Windows 下可以在资源管理器中按住SHIFT 右键选择在此处打开 PowerShell 窗口见 docs/images/POWERSHELL.png。六大操作详解所有操作在 spotdl/console/entry_point.py 中注册为OPERATIONS映射download、sync、save、meta、urlweb因启动方式特殊单独处理。启动流程会先解析参数、初始化日志与 Spotify 客户端、校验 save 文件后缀必须以.spotdl结尾见 entry_point.py再按操作分发执行。download默认操作下载并嵌入元数据download是缺省操作将歌曲从 YouTube 下载到本地并把 Spotify 元数据曲名、艺术家、专辑、封面、歌词等嵌入音频文件。支持直接传入歌曲/专辑/歌单/艺术家链接也支持文本搜索注意加引号# 单曲 spotdl download https://open.spotify.com/track/0VjIjW4GlUZAMYd2vXMi3b # 专辑 spotdl download https://open.spotify.com/album/4yP0hdKOZPNshxUOjY0cZj # 歌单 spotdl download https://open.spotify.com/playlist/37i9dQZF1E8UXBoz02kGID # 艺术家全部歌曲 spotdl download https://open.spotify.com/artist/1Xyo4u8uXC1ZmMpatF05PJ # 文本搜索带引号 spotdl download The Weeknd - Blinding Lights # 手动指定音频源与元数据来源引号必须保留 spotdl download YouTubeURL|SpotifyURL多个任务可以一次排队用空格分隔、顺序无关spotdl download The Weeknd - Blinding Lights https://open.spotify.com/playlist/37i9dQZF1E8UXBoz02kGID ...上述 URL 类型识别逻辑可在 spotdl/utils/search.py 的get_simple_songs中看到它按模式匹配track/playlist/album/artist/user链接、YouTube Music 链接、.spotdl保存文件、saved等特殊查询还支持album:、playlist:、artist:前缀的搜索语法。save仅保存元数据不下载save操作只从 Spotify 抓取歌曲元数据并写入.spotdl文件JSON 格式供后续download/sync复用spotdl save [query] --save-file {filename}.spotdl例如spotdl save The Weeknd - Blinding Lights --save-file the-weeknd.spotdl支持--preload预加载下载 URL以加快后续下载速度spotdl save The Weeknd - Blinding Lights --save-file the-weeknd.spotdl --preload保存文件路径为-时输出到 stdout。从源码看spotdl/console/save.pysave使用信号量限流的多线程池并行处理每首歌--preload时调用downloader.search(song)得到匹配的下载 URL 一并写入 JSON同时还会抓取歌词存入lyrics字段。web启动 Web 界面web操作启动一个本地 Web 界面基于 FastAPI模板见 spotdl/web/适合不熟悉命令行的用户但它功能有限仅支持下载单首歌曲spotdl web默认情况下 Web UI 把文件下载到专用会话目录若希望输出目录跟随--output配置可加--web-use-output-dir。无参数运行预构建可执行文件时也会默认启动 Web UIentry_point.py 中is_executable()判断。url获取下载地址url操作为查询中的每首歌输出对应的、用户可读的下载 URL即解析 Spotify 歌曲后匹配到的 YouTube/音频源原始链接spotdl url [query]其实现spotdl/console/url.py对每首歌调用downloader.search(song)获取匹配数据再通过首选音频 provider 的get_download_metadata(data)[original_url]打印原始下载地址。sync同步本地目录与歌单sync操作让本地目录与 Spotify 歌单/专辑保持同步新增的歌曲会被下载已移除的歌曲会被删除其他文件不受影响。首次使用先初始化同步文件spotdl sync [query] --save-file {filename}.spotdl例如spotdl sync https://open.spotify.com/playlist/37i9dQZF1E8UXBoz02kGID --save-file the-weeknd.sync.spotdl之后只需传入该同步文件即可增量更新spotdl sync the-weeknd.sync.spotdl如果不想删除已不在歌单中的歌曲追加--sync-without-deletingspotdl sync the-weeknd.sync.spotdl --sync-without-deleting同步文件的实现见 spotdl/console/sync.py首次同步会把{type: sync, query: ..., songs: [...]}写入 JSON 文件并执行首次下载后续同步时读取该文件对比歌单当前歌曲的 URL 与历史记录删除 URL 已消失的旧文件、重命名因输出模板变化而改变路径的文件例如输出模板含{list-position}时再下载新增歌曲并回写同步文件。注意同步文件必须以.spotdl结尾且不能同时把.spotdl文件作为查询和保存目标。meta更新已有文件的元数据meta操作为已下载的本地音频文件补充或更新元数据曲名、艺术家、专辑、封面等适用于之前下载时元数据缺失或需要修正的场景。可用--force-update-metadata强制覆盖已有元数据--skip-album-art跳过封面下载--redownload配合--format可把本地歌曲重新下载为不同格式。支持的查询类型结合 spotdl/utils/search.py 的实现QUERY支持的类型非常丰富查询说明https://open.spotify.com/track/...单曲https://open.spotify.com/album/...专辑https://open.spotify.com/playlist/...歌单https://open.spotify.com/artist/...艺术家的全部歌曲https://open.spotify.com/user/...某用户的公开歌单需登录歌手 - 歌名文本搜索album:专辑名/playlist:歌单名/artist:歌手名按类型搜索可混用以提高精度YouTubeURL\|SpotifyURL手动指定音频来源与元数据来源track 级链接saved我喜欢的音乐需--user-authall-user-playlists我创建的全部歌单需--user-authall-saved-playlists我收藏的全部歌单需--user-authall-user-followed-artists我关注的全部艺术家需--user-authall-user-saved-albums我保存的全部专辑需--user-authxxx.spotdl读取之前save/sync生成的元数据文件需要--user-auth的查询在未登录时会直接报错entry_point.py 中会检查saved查询与user_auth设置。此外YouTube Music 的专辑/歌单链接music.youtube.com/watch?v...、?list...也被原生支持且支持 YouTubeMusicURL|SpotifyURL 配对以校验两个列表长度一致。音乐来源与音频质量spotDL以 YouTube 作为音乐下载来源这是为了规避直接下载 Spotify 音频带来的问题。仓库同时内置了多个可切换的音频 provider见 spotdl/download/downloader.pyyoutube、youtube-music默认、soundcloud、bandcamp、piped、slider-kz可通过--audio指定多个并按顺序回退。法律提示用户需自行承担使用后果与潜在法律风险。项目不支持未授权下载受版权保护的内容也不对用户行为负责。音频格式与码率下载文件默认输出MP3格式跨平台兼容性最佳同时支持--format切换为m4a、opus、flac、ogg、wav。码率方面需要特别注意spotDL 始终以最高可用码率下载普通用户最高128 kbpsYouTube Music Premium 用户最高256 kbpsM4A 格式使用--bitrate标志会把文件转码到指定码率可能造成文件变大而音质没有明显提升追求小体积建议保持默认或更低值若希望保留原始码率不做转换可对M4A/OPUS等格式使用--bitrate disable跳过转码步骤--bitrate可选值包括auto、disable、固定码率8k–320k以及 0–9 的可变码率VBRauto使用原始文件码率对 m4a/opusauto与disable都会跳过转换。通过 YouTube Music Premium 获取 256 kbps 高音质在 YouTube Music 设置中把音质调到最高获取music.youtube.com域名的 cookies.txt使用浏览器的 cookies 导出扩展在 spotDL 命令中加入--cookie-file cookies.txt将音频格式改为M4A或OPUS以获得原始高码率文件。官方建议的最佳音质组合是M4A/OPUS 格式 --bitrate disable。相关完整说明见 docs/usage.md。配置文件spotDL 支持通过 JSON 配置文件持久化所有命令行选项无需每次输入。配置文件位置与生成WindowsC:\Users\user\.spotdl\config.jsonLinux~/.config/spotdl/config.jsonv4.4.3 之前的旧位置~/.spotdl/config.json若仍存在也会被兼容使用生成会覆盖已有配置与加载spotdl --generate-config配置文件若已存在会被自动加载也可以用--config显式指定加载。若不想自动加载把配置中的load_config改为false{ load_config: false }默认配置解读生成出的默认配置如下省略了部分注释字段{ client_id: f8a606e5583643beaa27ce62c48e3fc1, client_secret: f6f4c8f73f0649939286cf417c811607, user_auth: false, max_retries: 3, audio_providers: [youtube-music], lyrics_providers: [genius, azlyrics, musixmatch], output: {artists} - {title}.{output-ext}, overwrite: skip, bitrate: 128k, format: mp3, threads: 4, filter_results: true, load_config: true, log_level: INFO, port: 8800, host: localhost }几个关键字段说明audio_providers/lyrics_providers音频与歌词 provider 列表按顺序回退。歌词 provider 支持genius、musixmatch、azlyrics、synced后者的同步歌词可能需要--generate-lrc配合某些播放器overwriteskip/metadata/force控制已存在文件的处理方式threads下载线程数默认 4bitrate输出码率默认128kport/hostWeb UI 服务监听地址默认localhost:8800cookie_fileYTMusic Premium 高音质下载所需的 cookies 文件路径restrictstrict/ascii/none限制文件名为安全字符集以提升兼容性playlist_numbering把歌单中的每首歌的专辑名设为歌单名、封面设为歌单图标。output 模板变量output键支持丰富的模板变量同样适用于--search-query官方文档给出了完整表格见 docs/usage.md变量含义示例{title}歌曲标题Dark Horse{artists}歌曲艺术家可多个Katy Perry, Juicy J{artist}主艺术家Katy Perry{album}专辑名PRISM{album-artist}专辑主艺术家Katy Perry{genre}流派dance pop{disc-number}多碟发行中的碟号1{disc-count}专辑总碟数1{duration}歌曲时长秒215.672{year}发行年份2013{original-date}原始发行日期2013-01-01{track-number}专辑内曲目序号06{tracks-count}专辑曲目总数13{isrc}国际标准音像制品编码USUM71311296{track-id}Spotify 歌曲 ID4jbmgIyjGoXjY01XxatOx6{publisher}唱片公司Capitol Records (CAP){list-length}歌单内项目总数10{list-position}歌曲在歌单中的位置1{list-name}歌单名称Saved{output-ext}文件扩展名mp3命令行选项速查spotdl -h输出的完整选项非常庞大这里按功能分组整理核心选项完整列表见 docs/usage.md主选项--audio音频 provider、--lyrics歌词 provider、--search-query搜索模板、--dont-filter-results、--album-type {single,album,compilation}、--only-verified-resultsSpotify 选项--user-authOAuth 登录、--client-id、--client-secret、--auth-token、--cache-path、--no-cache、--max-retries、--headless、--use-cache-file、--use-official-api使用官方 Web API 而非默认的 SpotipyFree 客户端FFmpeg 选项--ffmpeg、--threads、--bitrate、--ffmpeg-args输出选项--format、--save-file、--preload、--output、--m3u、--cookie-file、--overwrite、--restrict、--print-errors、--save-errors、--sponsor-block跳过 YouTube 赞助段落、--archive、--playlist-numbering、--playlist-retain-track-cover、--scan-for-songs、--fetch-albums、--id3-separator、--ytm-data、--add-unavailable、--generate-lrc、--force-update-metadata、--sync-without-deleting、--max-filename-length、--yt-dlp-args、--detect-formats、--redownload、--skip-album-art、--ignore-albums、--skip-explicit、--proxy、--create-skip-file、--respect-skip-file、--sync-remove-lrcWeb 选项--host、--port、--keep-alive、--allowed-origins、--web-use-output-dir、--keep-sessions、--enable-tls、--cert-file、--key-file、--ca-file其他--log-level、--simple-tui、--log-format、--download-ffmpeg、--download-deno、--generate-config、--check-for-updates、--profile性能分析调试用、--version/-v。其中--overwrite与--scan-for-songs组合时force会移除所有重复文件metadata只对最新文件应用元数据并移除其余重复项--m3u支持{list}为每个列表生成与{list[0]}基于第一个列表等模板。--save-errors会把下载失败等错误写入文件配合长歌单排查非常实用——错误日志写入逻辑在 entry_point.py 的异常处理分支中。参与贡献与许可本项目欢迎社区贡献贡献指南见 docs/CONTRIBUTING.md含开发环境搭建说明行为准则见 docs/CODE_OF_CONDUCT.md。测试用例集中在 tests/ 目录覆盖参数解析、配置、搜索、各 provider、下载器与各控制台模块。项目以MIT 许可证开源完整许可文本见 LICENSE。结语spotDL v4 以Spotify 元数据 YouTube 音频的间接方案提供了一条从歌单到本地音乐库的完整流水线save备份元数据、download批量下载、sync持续同步、meta修复标签、web提供图形入口、url输出直链。结合仓库内 docs/usage.md 的完整参数说明与 docs/troubleshooting.md 的排障指引无论是个人收藏音乐还是维护大型歌单都能找到对应的自动化方案。【免费下载链接】spotify-downloaderDownload your Spotify playlists and songs along with album art and metadata (from YouTube if a match is found).项目地址: https://gitcode.com/GitHub_Trending/sp/spotify-downloader创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考