spotDL 安装指南：Python / FFmpeg / Deno / Docker 多方案完整部署教程

2026-09-10 16:59:16作者：仰钰奇

本文是 spotDL（一个免费开源的 Spotify 歌单与音乐下载工具，能从 YouTube 匹配并下载歌曲，同时附带专辑封面与元数据）的官方安装指南。全文围绕 docs/installation.md 展开，覆盖从 Python 环境搭建、FFmpeg 与 Deno 运行时准备，到预编译可执行文件、Docker / Docker Compose、Termux 等全部安装路径。读完本文，你将能够依据自己的操作系统与使用场景，选择最合适的安装方式，并完成 spotDL 的首次运行验证。

安装前的环境概览

spotDL 是一个跨平台工具，安装前需要先明确两点：你打算以哪种方式运行它（Python 包、预编译可执行文件，还是 Docker 容器），以及你的系统里是否已具备两个关键运行时——FFmpeg（音频转码与元数据嵌入）与 Deno（YouTube 下载辅助运行时）。

从仓库的 pyproject.toml 可以看到，spotDL 当前版本为 4.5.0，requires-python = ">=3.10,<3.15"，即官方支持 Python 3.10 ～ 3.14。项目通过 [project.scripts] 注册了 spotdl = "spotdl:console_entry_point" 控制台入口，因此安装后可以直接在终端执行 spotdl 命令，也可用 python -m spotdl 以模块方式运行。

方式一：通过 Python 安装（推荐）

官方推荐通过 PyPI 安装，这是最省事、更新最方便的方式。

1. 前置条件（Prerequisites）

在正式安装 spotDL 之前，请确认你的系统满足以下条件：

Windows 用户：先安装 Visual C++ 2019 Redistributable（文中给出的官方链接即最新支持的 VC++ Redistributable 页面），随后再安装 Python 与 FFmpeg；
Python 3.10 - 3.14，并确保已添加到 PATH（见下文）；
FFmpeg 4.2 或更高版本，同样需要添加到 PATH。

版本说明：安装文档中要求"v3.7 或更高"，但当前仓库 pyproject.toml 明确声明 >=3.10,<3.15，请以 3.10 及以上版本为准，以避免运行时依赖解析问题。

2. 安装 Python 并加入 PATH

官方建议安装最新版 Python。在 Windows 安装向导中，务必勾选 "Add to PATH"（添加到 PATH）选项，否则终端无法直接识别 python / pip 命令：

3. 安装 spotDL

非 Windows（如 macOS / UNIX）用户，请将下文所有命令中的 pip 换成 pip3、python 换成 python3。

打开终端——Windows 用"命令提示符（Command Prompt）"、macOS 用"终端（Terminal）"、UNIX 用 Bash 或 Zsh——先验证 Python 安装是否成功：

python -V

确认版本号符合要求后，执行安装：

pip install spotdl

如需升级到最新版本，在 docs/index.md 中给出的更新命令为：

pip install --upgrade spotdl

如果 pip 命令不可用，可以尝试用 python -m pip install spotdl 调用模块级的 pip。

安装 FFmpeg：转码与元数据嵌入的核心依赖

spotDL 使用 YouTube 作为音频来源，下载后需要用 FFmpeg 完成音频转码（如转换为 mp3/flac/ogg/opus/m4a/wav）以及元数据（标题、艺术家、封面）的嵌入。因此 FFmpeg 是 spotDL 的必需依赖。

方式 A：仅给 spotDL 使用（推荐）

如果 FFmpeg 只服务于 spotDL，可以将其安装到 spotDL 的本地目录中，一条命令即可完成：

spotdl --download-ffmpeg

从源码看，该命令在 spotdl/utils/arguments.py 中定义为 --download-ffmpeg（store_true 布尔参数），实际下载逻辑位于 spotdl/utils/ffmpeg.py：它根据当前操作系统与 CPU 架构，从 FFMPEG_URLS 映射表（支持 windows/linux/darwin 三大平台的 x64、arm64 等架构）下载对应静态二进制，保存到 spotDL 目录下名为 ffmpeg（Windows 下为 ffmpeg.exe）的文件，并在 Linux/macOS 上自动添加可执行权限。

spotDL 目录的位置由 spotdl/utils/config.py 中的 get_spotdl_path() 决定：

Linux：遵循 XDG 规范，优先使用 ~/.config/spotdl；若存在旧版目录 ~/.spotdl 则向后兼容使用之；全新用户自动创建 ~/.config/spotdl；
Windows 等非 Linux 系统：默认使用 ~/.spotdl。

另外值得注意的是，在 spotdl/console/entry_point.py 中，当以预编译可执行文件方式运行时，若检测到 FFmpeg 未安装，程序会自动触发 download_ffmpeg() 进行下载；若仍检测不到，会抛出 FFmpegError 并提示运行 spotdl --download-ffmpeg 或通过 spotdl --ffmpeg /path/to/ffmpeg 指定路径。

方式 B：系统级安装

如果你希望 FFmpeg 在系统全局可用，可按平台安装：

Windows：参考 Windows 平台上的 FFmpeg 安装教程（官方指南指向 windowsloop 的图文教程）；
macOS：brew install ffmpeg（Homebrew）；
Linux：sudo apt install ffmpeg，或使用你所用发行版的包管理器。

提示：FFmpeg 4.2 及以上版本即可满足 spotDL 需求。仓库中 Dockerfile 的镜像构建也直接通过 apk add ffmpeg 在 Alpine 中安装了系统级 FFmpeg。

安装 Deno：YouTube 下载的强力辅助

spotDL 底层使用 yt-dlp 进行 YouTube 下载（依赖声明见 pyproject.toml 中的 yt-dlp[default]）。部分视频（包括标记为"儿童专属（made for kids）"的内容）需要 JavaScript 运行时 Deno 才能成功下载。官方强烈建议安装 Deno，否则某些歌曲可能下载失败。

方式 A：仅给 spotDL 使用

spotdl --download-deno

该命令同样在 spotdl/utils/arguments.py 中定义。底层实现见 spotdl/utils/deno.py：它会先从 https://dl.deno.land/release-latest.txt 获取最新版本号，再根据平台与架构（DENO_TARGETS 映射了 windows/linux/darwin 对应的 MSVC/GNU/Apple 目标三元组）下载对应 zip 压缩包，解压出 deno（Windows 下为 deno.exe）二进制到 spotDL 目录，并在 Linux/macOS 上赋予可执行权限。

下载完成后，spotDL 会通过 spotdl/utils/deno.py 中的 get_local_deno_yt_dlp_options() 把本地 Deno 路径注入 yt-dlp 的 js_runtimes 配置。如果 Deno 缺失，warn_if_deno_missing() 会打印警告，提示运行 spotdl --download-deno 或系统级安装 Deno。

方式 B：系统级安装

若希望 Deno 全局可用，请参阅官方 Deno 安装指南（官方安装文档会覆盖 Windows/macOS/Linux 的脚本安装方式）。

方式二：使用预编译可执行文件（免 Python 环境）

如果不想管理 Python 环境，可以从项目 Releases 页面下载预编译的最新版可执行文件（Windows/macOS/Linux 均有对应构建产物）。

运行 Web UI（默认入口）

预编译可执行文件在不传任何参数时（例如直接双击运行），默认会启动 Web UI，无需命令行操作即可通过浏览器使用下载功能：

从源码角度印证：在 spotdl/console/entry_point.py 中，当程序处于 frozen（打包）状态或指定 web 操作时，会调用 web() 启动 Web 服务，并且 frozen 状态下默认将输出目录设为当前目录（web_use_output_dir = True）。

运行 CLI

如果要用命令行接口，在终端中执行可执行文件并传入操作与 URL：

./spotdl-vX.X.X operation [urls]

其中 X.X.X 为版本号，operation 为 download、sync、save、meta、url 等操作之一（完整操作注册见 spotdl/console/entry_point.py），[urls] 为 Spotify 歌曲/歌单/专辑链接。

需要补充的是：除安装文档外，docs/index.md 还提供了从源码构建可执行文件的路径（使用 uv sync + uv run scripts/build.py，产物输出到 dist/ 目录），适合开发者或无法直接使用 Releases 产物的场景。

方式三：Docker 部署

spotDL 提供官方 Docker 镜像，适合服务端、NAS 或希望环境完全隔离的场景。使用前请先安装 Docker 与 Docker Compose（官方 Docker 文档链接已在上文环境概览中给出）。

1. 使用仓库内 Dockerfile 构建本地镜像

构建镜像：
```
docker build -t spotdl .
```
查看 spotDL 所有可用选项：
```
docker run --rm spotdl --help
```
下载一首歌曲：
```
docker run --rm -v $(pwd):/music spotdl download https://open.spotify.com/track/0VjIjW4GlUZAMYd2vXMi3b
```
权限提醒：如果你把宿主机目录 bind-mount 到 /music（如 $(pwd):/music），该目录必须对容器内的 UID/GID 可写，否则容器内 spotdl 将无法写入下载文件。

从仓库的 Dockerfile 可以看到镜像基于 python:3.13-alpine，通过 apk 安装了 ffmpeg、aria2、git、openssl 等依赖，用 uv sync --no-dev 安装项目依赖，创建了非 root 的 spotdl 用户，并声明了 VOLUME /music 作为下载输出目录，入口为 uv run ... spotdl。镜像还支持通过构建参数自定义用户/组 ID（默认均为 1000），这正是上面权限提醒的实现依据。

2. 使用 Docker Hub 官方镜像

拉取镜像：
```
docker pull spotdl/spotify-downloader
```

用官方镜像下载歌曲：

docker run --rm -v $(pwd):/music spotdl/spotify-downloader download https://open.spotify.com/track/0VjIjW4GlUZAMYd2vXMi3b

创建持久化容器：
```
docker create \
  --name=spotdl \
  -v <path to data>:/music \
  spotdl/spotify-downloader
```
将 <path to data> 替换为你想保存音乐文件的宿主机目录。

3. 使用 Docker Compose（推荐管理权限）

如果你希望 Docker 自动处理文件权限归属，推荐使用 Docker Compose。仓库根目录已提供现成的 docker-compose.yml。

设置你的用户与组 ID（确保下载的文件归属你的用户而非 root）：
```
export PUID=$(id -u)
export PGID=$(id -g)
```
从 docker-compose.yml 可以看到，这两个环境变量会作为构建参数 UID/GID 传入镜像构建（默认回退为 1000），并声明了命名卷 spotdl_music:/music 与 TZ 时区环境变量。
构建镜像：
```
docker compose build
```

下载一首歌曲：

docker compose run --rm spotdl download https://open.spotify.com/track/0VjIjW4GlUZAMYd2vXMi3b

导出下载文件：Docker Compose 会把下载内容保存在命名卷 spotdl_music:/music 中，可用以下命令拷贝到宿主机：
```
docker compose up --no-start spotdl
mkdir -p downloads
docker compose cp spotdl:/music/. ./downloads/
```

其他安装方式

Termux（Android 终端模拟器）

spotDL 为 Termux 提供了专用的一键安装脚本（位于 scripts/termux.sh）：

curl -L https://raw.githubusercontent.com/spotDL/spotify-downloader/master/scripts/termux.sh | sh

从 scripts/termux.sh 的源码可以看到，脚本依次执行：termux-setup-storage 授权存储、pkg update -y 更新软件源、pkg install -y python ffmpeg rust binutils 安装依赖、pip install -U spotdl 安装 spotDL，最后还会生成一个 $HOME/bin/termux-url-opener 钩子脚本——之后在 Termux 中点击 Spotify 分享链接即可自动触发 spotDL 下载到 ~/storage/shared/songs 目录。

Arch Linux（AUR 包）

Arch 用户可以直接安装 AUR 上的 spotdl 包（包名 spotdl），通过 AUR 助手（如 yay -S spotdl）或手动从 AUR 构建即可，无需手动配置 Python 环境。

spotDL 将文件下载到哪里？

spotDL 默认把文件下载到运行 spotdl 命令时所在的当前目录。

因此，请先在 PowerShell / CMD / Terminal 等终端中 cd 到你希望保存音乐的目标文件夹，再执行 spotdl。

Windows 快捷技巧：在目标文件夹中按住 SHIFT + 右键，选择"在此处打开 PowerShell 窗口（Open PowerShell window here）"，即可直接在当前文件夹打开终端：

安装后的首次验证与常见问题

完成任意一种方式安装后，可以按以下顺序快速验证环境是否就绪：

验证 spotDL 版本：spotdl --version（该参数在 spotdl/utils/arguments.py 中注册，输出 _version.py 中的版本号）；
查看全部可用参数：spotdl -h；
验证 FFmpeg：spotdl --download-ffmpeg 会下载本地 FFmpeg；系统级安装时可用 ffmpeg -version 检查；
验证 Deno：spotdl --download-deno 会下载本地 Deno；deno --version 可检查系统级安装；
无参数直接运行 spotdl 会启动 Web UI（预编译版本默认行为）。

如果下载 YouTube 视频时出现与 JavaScript 执行相关的报错，优先排查 Deno 是否安装；如果出现转码或嵌入元数据失败，优先排查 FFmpeg 的版本与 PATH。对于 Docker 部署，若容器报写入失败，请检查挂载目录是否对容器 UID/GID 可写（或改用 Docker Compose 并正确设置 PUID/PGID）。