Skip to content

spotDL

spotDL finds the music that matches your Spotify metadata and downloads it — with tags, album art and lyrics — from YouTube and other providers.

spotDL v5 is a ground-up rewrite. Instead of a monolithic CLI, it is now:

  • a server that resolves metadata, searches providers, ranks audio matches (with community voting) and serves lyrics;
  • the spotdl CLI and a built-in TUI;
  • a web UI, bundled in the package (no runtime download).

You can use spotDL three ways, all from the same spotdl package:

Mode What runs Best for
Community server The CLI talks to the shared instance at api.spotdl.dev Getting started, occasional use
Embedded The CLI runs the server in-process on your machine Offline / private use, heavy downloading
Self-hosted You run the server (Docker/Railway) for your household or team A shared instance you control

Pre-release

v5 is a pre-release. A plain pip install spotdl still installs the stable v4 line until v5 reaches general availability (GA). See Installation for how to try the pre-release, and Migrating from v4 if you are coming from v4.

Quick start

pip install --pre spotdl        # pre-release; installs v5
spotdl "https://open.spotify.com/track/..."   # download a track
spotdl                          # no arguments in a terminal → launches the TUI

The CLI defaults to the community server at https://api.spotdl.dev for metadata and matching, and downloads audio locally. No Spotify API keys are required — metadata is served by the server.

Where to next

spotDL downloads metadata from the Spotify catalog and audio from providers such as YouTube. Use it only for content you are legally permitted to download. spotDL is not affiliated with Spotify or any provider. Released under the MIT license.