spotDL/spotify-downloader

What it does

spotDL takes Spotify playlist, album, or track URLs, searches YouTube for matching music, and downloads the audio with album art, lyrics, and metadata embedded. It is aimed at users who want offline copies of Spotify collections and are comfortable working from a terminal. SpotDL itself does not host or stream the audio: it uses YouTube as the download source, which the project says avoids issues tied to downloading directly from Spotify.

The CLI has several operations beyond the default download: save stores only Spotify metadata, sync keeps a directory aligned with a playlist file, url prints user-friendly song URLs, web starts a limited browser interface for single tracks, and meta updates metadata on existing song files.

Quick start

Requirements: Python and pip, plus FFmpeg. Deno is strongly recommended because spotDL relies on yt-dlp for YouTube downloads and some videos need Deno; without it, some songs, including videos marked "made for kids", may fail to download.

1. Install spotDL from PyPI: pip install spotdl. On some systems use pip3. Package users can also install FFmpeg into the spotDL directory with spotdl --download-ffmpeg, and Deno with spotdl --download-deno.
2. Download a playlist or track by passing its Spotify URL: spotdl [urls]. The default operation is download; it fetches songs from YouTube and embeds metadata.
3. If running as a script does not work, use the module form: python -m spotdl [urls].

Other installation routes include prebuilt executables from the Releases tab, an AUR package on Arch, a Termux install script, Docker, and building from source with uv. Check the installation guide for the route you choose.

To keep a local folder in sync with a playlist, first create a sync file with spotdl sync [query] --save-file {filename}.spotdl, then rerun spotdl sync {filename}.spotdl; newly added songs are downloaded and removed songs are deleted. Use spotdl -h for all options.

Constraints

• FFmpeg is required. Deno is strongly recommended, not merely optional, for reliable YouTube downloads through yt-dlp.
• Audio comes from YouTube. The project says it always targets the highest available bitrate: 128 kbps for regular users and 256 kbps for YouTube Music premium users.
• The project states that users are responsible for their actions and potential legal consequences, and that it does not support unauthorized downloading of copyrighted material.
• The web interface is feature-limited and only supports downloading individual songs.
• The project is MIT licensed.

HotRepo's take

No daily ranking, star-curve sample, or Hacker News thread is recorded for this repository in the available HotRepo data, so there is no trend or discussion signal to report. The useful technical facts here are the long-running CLI scope and the dependency chain: spotDL's output quality depends on YouTube matching and on FFmpeg/Deno being available, and the default 128 kbps ceiling for regular users is a practical constraint rather than a bug.

Project source and documentation