spotify-dl: turn a Spotify playlist into a folder of MP3 files

The tool does not download from Spotify at all

The most important sentence in the README is a negative one. The author says spotify-dl does not download anything from Spotify. It picks up the metadata from the Spotify API and then uses yt-dlp to download the song. The project description says the same thing, downloads songs from any Spotify playlist, album or track, and the topic list includes mp3, playlist and spotify.

That distinction defines the whole design. Spotify is used as the catalogue and as the source of the track list, titles, artists and album names, and it is the music itself that comes from somewhere else entirely. The Spotify side is handled by spotipy, the official Python client, and the YouTube side by yt-dlp, the downloader. The dependency list in the repository makes the shape of the tool obvious: spotipy around 2.21, yt-dlp at 2023.3.4 or newer, ytmusicapi around 1.6.0 for YouTube Music, mutagen around 1.45 for writing tags into the audio files, Levenshtein around 0.27.3 for string distance, rich for terminal output, sentry_sdk for crash reporting, and urllib3.

The Levenshtein dependency is the tell for how the matching works. A candidate title and artist from YouTube search is compared as a string against the Spotify metadata, and the closest match wins. That is a heuristic, and it is the project's main weakness, which is worth understanding before you rely on it.

The author's motivation is also stated plainly. He wanted an easy way to grab the songs in his library so he could download it and use it offline, and he says he no longer uses it but continues to maintain it. That sentence tells you what kind of project this is: a personal utility that someone else found useful and keeps alive.

Running it is a pip install and one command

Installation is a pip install of the package from PyPI, and the entry point is a console script named spotify_dl.

pip3 install spotify_dl

The basic invocation takes one or more playlist links.

spotify_dl -l spotify_playlist_link_1 spotify_playlist_link_2

Parallelism is controlled with the -mc flag, which takes the number of cores to use. The documentation notes that if the number is too high, spotify-dl will set it to one less than the maximum number of cores you have, which is a small piece of defensive behaviour that prevents the tool from saturating a machine.

spotify_dl -mc 4 -l spotify_playlist_link_1 spotify_playlist_link_2

There is a SponsorBlock integration that skips non-music sections when downloading from YouTube, which is disabled by default and enabled with the -s flag.

spotify_dl -l spotify_playlist_link_1 -s y

Verbose output comes from appending -V, and the -o flag sets the output directory, and the full argument list is available from -h.

spotify_dl -V -l spotify_playlist_link -o download_directory

spotify_dl -h

The package requires Python 3.8 or newer, and the setup metadata lists classifiers for 3.8 through 3.12. The richer documentation is in a GETTING_STARTED.md file in the repository, and the README links to it.

Docker, credentials and the settings file

The repository ships a Dockerfile, and it is short enough to be worth reading in full because it shows what the tool expects from the outside.

FROM python:3.8-slim

RUN apt-get update
RUN apt-get install -y ffmpeg
RUN pip3 install spotify_dl --upgrade

ENV SPOTIPY_CLIENT_ID=
ENV SPOTIPY_CLIENT_SECRET=

Two environment variables carry the Spotify API credentials, and the image installs ffmpeg, which yt-dlp needs for the audio extraction and conversion steps. The image installs the package from PyPI rather than from the local source, so it tracks the published release rather than the working tree.

The credentials are what the spotipy dependency consumes, and they are the reason the tool needs a Spotify developer application rather than working anonymously. A .spotify_dl_settings.example.json file at the top of the repository is the template for the local settings file, and there is also a bulk_docker_download.sh script for running a bulk download through the container.

The build scripts in the repository, build.sh and build.bat, and the MANIFEST.in file show that this is a package that is built and published to PyPI, not just run from a clone. The tests directory and the Makefile hold the test setup, and the Makefile shows the test target doing a pip install of the package in editable mode followed by pytest with coverage over the tests directory. The clean target removes compiled Python files and also deletes the generated mp3 files and the downloaded_songs.txt from the tests directory, which tells you the test suite actually downloads audio as part of its run.

Matching is the weak point, and the tool knows it

The mechanism for finding a track is a search followed by a string distance comparison. Spotify gives you the title, the artist and the album. YouTube search gives you a set of candidate videos. Levenshtein distance ranks how close each candidate's title and artist are to the Spotify metadata, and the closest one is downloaded.

That approach has a predictable failure profile, and it is worth knowing about before you download a hundred tracks. A live recording uploaded by a fan will often match the title better than the official video does. A remastered version, a sped up version or a karaoke rendition carries the same title and artist, and string distance does not care which one you get. A song with a featured artist listed differently on the two services will fail to match even when the correct video exists. And the album art and the tags are taken from Spotify, so a mismatched audio file ends up with correct metadata and wrong content, which is the worst combination, because nothing in the output reveals the problem.

The ytmusicapi dependency suggests one mitigation, since YouTube Music has a slightly different catalogue and search behaviour than the main site. The SponsorBlock integration helps with the shape of the audio rather than the identity of it.

None of this is a flaw the author hid. The project is described as Production/Stable in its package metadata, but the honest reading of the mechanism is that it is a best effort matcher with no verification step. That is the single fact a user should carry into the decision.

Where spotify-dl is the wrong tool

Three cases argue against it, and the first one is not about the software. spotify-dl has no rights check of any kind. It takes a link you give it and downloads whatever YouTube search turns up, so whether the resulting file is yours to keep depends entirely on your subscription and on the rights to the recordings, and the tool has nothing to say about it. For your own library and your own use that is a defensible position, since you have paid for access and are making a personal offline copy. For anything else, the tool is not the place to start, and a downloader that is handed a curated list of arbitrary links will do what it is asked.

The second case is a reliable, long lived setup. The tool's behaviour depends on the shape of YouTube search results and on YouTube's own anti-download measures, both of which change without notice, and the yt-dlp dependency is there precisely because the other side moves. A library you depend on for a daily workflow is a bad fit for that, and the fact that the newest tagged release is v8.9.0 from 2024-01-07 while the last push was on 2026-07-10 suggests the project is maintained in bursts rather than on a release cadence.

The third case is a task that has an authorised answer. Spotify has an offline mode, and offline playback of downloaded content is exactly the problem the author was solving when he wrote it, and he says he no longer uses the tool for that. If your goal is listening to your library on a plane, the answer already exists inside the service you pay for.

There is a smaller operational point. The test suite downloads real audio, as the Makefile's clean target shows when it removes mp3 files and downloaded_songs.txt from the tests directory, so running the tests means making network requests and writing media to disk. That is a normal thing for an integration test to do, but it is worth knowing before you run it in a sandbox.

Editorial conclusion

spotify-dl suits a listener who already subscribes to Spotify, wants an offline copy of a playlist they control, and accepts that the tool matches tracks by searching rather than by using an authorised source. It does not suit anyone who wants an offline copy of music they do not have rights to, since the tool has no rights check of any kind, and it does not suit a setup that must keep working next year, because the matching depends on YouTube search results. Before you run it on a large playlist, test it on a handful of tracks and listen to the output, and note that the last push was on 2026-07-10 with the newest release v8.9.0 from 2024-01-07.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. SathyaBhat/spotify-dl on GitHub