Skip to content
Get packs

Guide · Open source

How to use spotify-downloader (spotDL): install and download playlists

Updated · written with AI from the project's own documentation and checked against our catalogue data

spotDL (spotdl/spotify-downloader) is a free, MIT-licensed command-line program written in Python. It takes Spotify song, album, or playlist links, finds matching tracks on YouTube, and downloads them with album art, lyrics, and metadata attached. This guide shows you how to install it with pip, set up its FFmpeg and Deno dependencies, and run the main operations, including sync for keeping a folder up to date with a playlist.

spotDLspotDL/spotify-downloader · ★ 26.6k · MIT

Quick start

  1. 1Install spotDL. Run pip install spotdl. Use pip3 if pip is not found on your system.
  2. 2Install FFmpeg. Run spotdl --download-ffmpeg to install FFmpeg into the spotDL directory.
  3. 3Install Deno. Run spotdl --download-deno. The README strongly recommends this, since some songs fail without it.
  4. 4Download a song or playlist. Run spotdl followed by one or more Spotify song, album, or playlist URLs.
  5. 5Create a sync file. Run spotdl sync with your playlist link and --save-file to create a .spotdl file.
  6. 6Update the folder later. Run spotdl sync with your .spotdl file to add new songs and remove deleted ones.

Install spotDL with pip

The recommended method is the Python package manager pip. spotDL is installed with a single command. The README notes that on some systems you may need to use pip3 instead of pip.

To update an existing installation, use the upgrade flag. Other options in the README include a prebuilt executable from the Releases tab, a Termux script, an Arch User Repository package, and Docker.

pip install spotdl

Install FFmpeg and Deno for spotDL

FFmpeg is required. If you only need it for spotDL, the README recommends installing it into the spotDL directory with a built-in command rather than system-wide.

Deno is strongly recommended. spotDL uses yt-dlp for YouTube downloads, and some videos need Deno to download successfully. Without Deno, spotDL may fail on some songs, including videos marked as "made for kids". If you only need Deno for spotDL, install it into the spotDL directory with the second command.

  • FFmpeg: install into the spotDL directory with spotdl --download-ffmpeg, or install system-wide (brew install ffmpeg on macOS, sudo apt install ffmpeg on Debian-based Linux).
  • Deno: install into the spotDL directory with spotdl --download-deno, or follow the official Deno installation guide for a system-wide install.
spotdl --download-ffmpeg spotdl --download-deno

Download songs or a playlist

The general form is spotdl [operation] [options] QUERY. If you run spotdl with only URLs, it uses the default operation, download, which downloads the songs from YouTube and embeds metadata. The query is usually a list of Spotify URLs.

If running spotdl as a script doesn't work, you can run it as a Python package instead. Run spotdl -h to see the full list of options.

spotdl [urls] python -m spotdl [urls]

Keep a folder in sync with a playlist

The sync operation compares a directory with the current state of a Spotify playlist. Newly added songs are downloaded and removed songs are deleted. No other songs are downloaded and no other files are deleted.

Running sync with a playlist link creates a sync file. Use that file later to update the same directory.

  • Create the sync file with the --save-file option.
  • Re-run sync using the saved .spotdl file to update the folder.
spotdl sync [query] --save-file {filename}.spotdl spotdl sync {filename}.spotdl

Other operations: save, url, meta and web

Besides download and sync, the README lists several other operations. Each one is useful in specific cases.

  • save: saves only the metadata from Spotify without downloading anything.
  • url: prints a user-friendly URL for each song from the query.
  • meta: updates metadata for song files you already have.
  • web: starts a web interface. The README says it has limited features and only supports downloading individual songs.
spotdl save [query] --save-file {filename}.spotdl spotdl url [query]

Understand audio quality and legal responsibility

spotDL downloads from YouTube, which the README says is used to avoid issues with downloading directly from Spotify. The README states that spotDL aims for the highest possible bitrate: 128 kbps for regular users and 256 kbps for YouTube Music premium users.

The README places legal responsibility on users. It says the project does not support unauthorized downloading of copyrighted material and takes no responsibility for user actions. Check the copyright rules where you live before you download anything.

What people use it for

  • Keep an offline folder of songs from a Spotify playlist you already listen to.
  • Keep a local music folder synced with a playlist that changes over time, using sync.
  • Download albums or playlists with album art, lyrics, and metadata embedded in the files.
  • Fix or add metadata on existing song files with the meta operation.
  • Save playlist metadata to a .spotdl file with save, without downloading audio.

Frequently asked questions

Is spotDL free to use?

The project is released under the MIT License, as stated in the README and the license section. The source does not discuss pricing for any hosted service, so the MIT licence is the only licensing information provided.

How do I install spotDL?

The README's recommended method is pip install spotdl. To update, run pip install --upgrade spotdl. Some systems need pip3 instead of pip.

Do I need FFmpeg and Deno?

FFmpeg is required for spotDL. Deno is strongly recommended because some YouTube videos need it, and without it some songs may fail to download. You can install both into the spotDL directory with spotdl --download-ffmpeg and spotdl --download-deno.

Does spotDL download directly from Spotify?

No. The README says spotDL uses YouTube as the source for music downloads to avoid issues related to downloading music from Spotify directly.

Is it legal to use spotDL?

The README says users are responsible for their own actions and any legal consequences. It states that the project does not support unauthorized downloading of copyrighted material. Check the rules in your jurisdiction before downloading.

What are the alternatives to spotDL?

The comparable projects listed for this directory are yt-dlp, other Spotify-Downloader forks, and spotify-dl. The source does not compare their features or accuracy, so test them yourself to decide.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

spotDL suits people who are comfortable in a terminal, use Python and pip, and want local copies of Spotify playlists with album art, lyrics, and metadata. The sync operation is its strongest feature for keeping a folder aligned with a playlist. It is a poor fit if you want a point-and-click app, need guaranteed match accuracy, or need to be sure a download is permitted where you live.

Install options & downloads