---

在 ReadTheDocs 上阅读文档！

---

安装

有关更多详细信息，请参阅我们的 安装指南。

Python（推荐方法）

• 可通过运行 pip install spotdl 安装 spotDL。

• 要更新 spotDL，请运行 pip install --upgrade spotdl

  在某些系统上，你可能需要将 pip 改为 pip3。

其他选项

• 预构建可执行文件
  • 你可以从 发布选项卡 下载最新版本
• 在 Termux 上
  • curl -L https://raw.githubusercontent.com/spotDL/spotify-downloader/master/scripts/termux.sh | sh
• Arch 系统
  • spotDL 有一个 Arch 用户仓库（AUR）包。
• Docker

  • 构建镜像：

    docker build -t spotdl .
    

  • 使用 spotDL 参数启动容器（见下文部分）。你需要创建映射卷以访问歌曲文件

    docker run --rm -v $(pwd):/music spotdl download [trackUrl]
    

  • 有关 Docker Compose 和权限管理的 Docker 下载，请参阅 /docs/index.md 中的 Docker 部分。

  • 从源代码构建

    git clone https://github.com/spotDL/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

我们推荐使用上述方法，但若您希望在系统范围内安装 FFmpeg，请按照以下说明操作：

• Windows 教程
• OSX - brew install ffmpeg
• Linux - sudo apt install ffmpeg 或使用您的发行版包管理器

安装 Deno

我们强烈建议安装 Deno。spotDL 使用 yt-dlp 进行 YouTube 下载，部分视频需要 Deno 才能成功下载。如果没有 Deno，spotDL 可能无法下载某些歌曲，包括标记为“专为儿童制作”的视频。

如果 Deno 仅用于 spotDL，请将其安装到 spotDL 目录： spotdl --download-deno

如果您希望在系统范围内安装 Deno，请参考 Deno 官方安装指南。

使用方法

不使用选项的情况下使用 SpotDL：

spotdl [urls]

如果将 spotDL 作为脚本运行不起作用，你可以将其作为软件包运行：

python -m spotdl [urls]

一般用法：

spotdl [operation] [options] QUERY

spotDL 可以执行多种操作。默认 操作是 download，该操作会从 YouTube 下载歌曲并嵌入元数据。

spotDL 的查询内容通常是一系列 Spotify URL，但对于某些操作（如 sync），仅需提供单个链接或文件。 若要查看所有选项的列表，请使用 spotdl -h

支持的操作

• save：仅从 Spotify 保存元数据，不下载任何内容。

  • 使用方法： spotdl save [查询内容] --save-file {文件名}.spotdl

• web：启动 Web 界面，而非使用命令行。但该界面功能有限，仅支持下载单个歌曲。

• url：为查询内容中的每首歌曲获取用户友好的 URL。

  • 使用方法： spotdl url [查询内容]

• sync：更新目录。将目录与播放列表的当前状态进行比较。新添加的歌曲将被下载，已移除的歌曲将被删除。不会下载其他歌曲，也不会删除其他文件。

  • 使用方法： spotdl sync [查询内容] --save-file {文件名}.spotdl

    这将创建一个新的 sync 文件。若要在将来更新目录，请使用：

    spotdl sync {文件名}.spotdl

• meta：更新提供的歌曲文件的元数据。

音乐来源与音频质量

spotDL 使用 YouTube 作为音乐下载源。采用此方法是为了避免从 Spotify 下载音乐可能产生的任何问题。

注意 用户需对自己的行为及可能产生的法律后果负责。我们不支持未经授权下载受版权保护的材料，且对用户行为不承担任何责任。

音频质量

spotDL 从 YouTube 下载音乐，并旨在始终下载尽可能高的比特率；普通用户为 128 kbps，YouTube Music 高级用户为 256 kbps。

有关更多信息，请查看 音频格式 页面。

贡献指南

有兴趣参与贡献吗？请查看我们的 CONTRIBUTING.md，其中包含了有关贡献的资源以及搭建开发环境的指南。

以代码贡献者身份加入我们出色的社区

许可证

本项目基于 MIT 许可证授权。