# spotDL v4: Downloading Spotify Playlists Through YouTube > spotDL is a Python command line tool that reads Spotify playlists, finds matching audio on YouTube, and writes tagged files with cover art and lyrics. It is a metadata pipeline more than a music service, and its accuracy depends on how well the matching step behaves. **spotDL/spotify-downloader** — Download your Spotify playlists and songs along with album art and metadata (from YouTube if a match is found). - Repository: https://github.com/spotDL/spotify-downloader - Website: https://spotdl.readthedocs.io/en/latest/ - Stars: 26,205 · Forks: 2,268 - Language: Python - License: MIT - Published: 2026-09-21 · Updated: 2026-09-21 · Language: en - Canonical page: https://hysenlabs.com/projects/spotdl-spotify-downloader ## The gap spotDL fills between a Spotify playlist and a local library A Spotify playlist is a list of identifiers, not files. If you want that list to exist as audio you can move to a phone, a car stereo or a NAS, you need something that resolves each identifier to a downloadable source and then writes proper tags. spotDL does exactly that, and it is explicit about the substitution it makes: the README says it "finds songs from Spotify playlists on YouTube and downloads them", and the Music Sourcing section explains that YouTube is used "to avoid any issues related to downloading music from Spotify." So the Spotify side supplies the track list, the artist, the album and the artwork, while the audio bytes come from somewhere else entirely. The intended user is comfortable in a terminal. The project ships a web operation, but the README is blunt about it: `web` "has limited features and only supports downloading individual songs." Anyone wanting a browser-first experience with playlist support is outside what this tool currently offers. The rest of the audience is people who already think in terms of directories, sync files and cron jobs. ## How the matching pipeline works: Spotify metadata in, YouTube audio out The dependency list in pyproject.toml is the clearest description of the architecture. `spotipy` and `spotipyFree` handle the Spotify side, `ytmusicapi` and `yt-dlp` handle the YouTube side, `rapidfuzz` does fuzzy string comparison, `mutagen` writes tags, `syncedlyrics` fetches lyrics, and `fastapi` plus `uvicorn` back the web operation. That ordering matters. A track is read from Spotify, a search is issued against YouTube, and candidate results are scored. `rapidfuzz` exists because the match is rarely exact: official uploads, remasters, live versions and lyric videos all compete for the same song title. Once a candidate is chosen, `yt-dlp` retrieves the audio stream and FFmpeg handles the container work, after which `mutagen` writes the Spotify-sourced metadata and cover art into the file. The README is candid that this is not lossless. Audio quality is described as "128 kbps for regular users and 256 kbps for YouTube Music premium users", and the tool "is designed to always download the highest possible bitrate" within that ceiling. If your reference point is a streaming service's own encoding, this is a re-encode of a re-encode. The practical consequence is that spotDL is a convenience layer over YouTube, and its output quality is bounded by what YouTube serves, not by what Spotify streams. ## Installing spotDL and running a first download The README calls the Python route the recommended method. The package requires Python >=3.10 and <3.15 according to pyproject.toml, so a system Python older than 3.10 will fail at install time rather than at runtime. ```bash pip install spotdl ``` On some systems, the README notes, `pip` may need to be `pip3`. Two external binaries are then needed. FFmpeg is required; Deno is strongly recommended because "some videos require Deno to download successfully", including videos marked as made for kids. Both can be placed inside the spotDL installation directory rather than installed system-wide. ```bash spotdl --download-ffmpeg spotdl --download-deno ``` The first real use is a single track or playlist URL. Running spotDL with no operation defaults to `download`, which fetches from YouTube and embeds metadata. ```bash spotdl [urls] ``` Files land in the current directory. Expect one audio file per track with cover art and tags already written, which is the point of the tool: the metadata work is not a separate step you script yourself. ## The sync operation is the real feature, and the real risk Downloading a playlist once is a one-off. Keeping a directory aligned with a playlist that changes is the harder problem, and `sync` is spotDL's answer. The README describes it precisely: it "compares the directory with the current state of the playlist. Newly added songs will be downloaded and removed songs will be deleted. No other songs will be downloaded and no other files will be deleted." That last sentence is doing a lot of work, and it is also the sharpest edge in the tool. If a track disappears from the playlist, the corresponding file is removed from disk. A playlist edited carelessly, or a Spotify account whose playlist is temporarily unavailable, can turn into deleted local files. The mechanism is a saved state file rather than a live diff against your directory listing. ```bash spotdl sync [query] --save-file {filename}.spotdl spotdl sync {filename}.spotdl ``` The first command creates the sync file and the second updates the directory later. The README does not document rollback or a dry-run flag for sync, so the safe pattern is to point it at a directory you are willing to see pruned. This is a design trade-off, not a bug: a sync that never deletes is a sync that accumulates duplicates and stale entries forever. ## Metadata-only and URL operations for people who do not want YouTube audio Not every user wants the download half. The `save` operation writes only the metadata from Spotify and touches no audio, producing a `.spotdl` file. The `url` operation returns a user-friendly URL for each song in a query. The `meta` operation updates metadata on song files you already have. ```bash spotdl save [query] --save-file {filename}.spotdl spotdl url [query] ``` These are the operations to reach for if your concern is preserving the shape of a playlist as data, or relabeling a library you acquired elsewhere. They also make spotDL useful in a context where the YouTube matching step is the part you distrust: you can capture the Spotify metadata now and decide about audio later. The README does not describe a way to supply your own audio files and have spotDL match Spotify metadata onto them, so `meta` expects files that already carry enough information to identify themselves. ## Docker, Termux and the platforms people ask about Beyond pip, the README lists a prebuilt executable from the Releases tab, a Termux install script, an AUR package for Arch, and Docker. The Dockerfile is worth reading because it shows what the pip path hides: it installs `ffmpeg`, `aria2`, `openssl` and a build toolchain, creates a non-root `spotdl` user with configurable `UID` and `GID` build arguments, and runs `spotdl --download-deno` at image build time so the runtime container does not fetch it. The compose file wires this up with a named volume and a timezone variable. ```yaml services: spotdl: build: context: . args: UID: "${PUID:-1000}" GID: "${PGID:-1000}" image: "spotdl/spotify-downloader" volumes: - spotdl_music:/music environment: - TZ=${TZ:-UTC} ``` Two things stand out. The `UID` and `GID` arguments exist so that files written into a mounted volume are not owned by root, which is the usual failure mode when a containerized downloader writes to a host directory. And the image is built on `python:3.14-slim-bookworm`, so the container's Python version is fixed by the image rather than by your host. There is no Android build in the repository; the Termux script is the closest thing, and it is a shell script rather than an app. ## Licence, maintenance and the cost of keeping up spotDL is MIT licensed, stated in both the README and the `license = "MIT"` field in pyproject.toml. In practical terms that is permissive: you can use it, modify it and redistribute it, and the main obligation is preserving the copyright notice and licence text. This is not legal advice, and the licence covers the software rather than what you do with the files it produces. The README carries its own warning that "users are responsible for their actions and potential legal consequences" and that the project does not support unauthorized downloading of copyrighted material. The last push to the repository was on 2026-09-19, two days before this writing, and the most recent tagged release is v4.5.2 from 2026-07-20, described as a hotfix. The dependency ranges in pyproject.toml tell you where the upgrade cost sits: `yt-dlp[default]>=2026.07.04,<2027` is pinned to a calendar-versioned package that changes frequently because YouTube changes frequently. When downloads start failing for no obvious reason, the first thing to try is updating spotDL, since a newer release is likely to carry a newer yt-dlp bound. Deno and FFmpeg are separate binaries with their own update cadence, and the Docker image bakes both in, so a containerized deployment ages with the image rather than with your host. ## Conclusion spotDL suits people who already keep their library as local files and want playlist state to stay in sync, and it is a poor fit for anyone expecting Spotify's own audio stream, since the README states the source is YouTube. Verify your Python version against the >=3.10,<3.15 range in pyproject.toml, confirm FFmpeg and Deno are present, and run spotdl sync with a saved .spotdl file on a small playlist before pointing it at a large one, because sync deletes files that have left the playlist. ## FAQ ### How do I install spotDL? The README recommends installing it with pip, using `pip install spotdl` (or `pip3` on some systems). You then need FFmpeg, which spotDL can place in its own directory with `spotdl --download-ffmpeg`, and Deno is strongly recommended via `spotdl --download-deno`. Prebuilt executables, a Termux script, an AUR package and a Docker image are listed as other options. ### What is spotDL? It is a command line tool that finds songs from Spotify playlists on YouTube and downloads them along with album art, lyrics and metadata. It is written in Python, distributed on PyPI as the spotdl package, and licensed under MIT. ### Is converting Spotify to MP3 legal? The README does not make a legal determination. It states that users are responsible for their actions and potential legal consequences, that the project does not support unauthorized downloading of copyrighted material, and that it takes no responsibility for user actions. ## Sources - [License: MIT](https://github.com/spotDL/spotify-downloader/blob/master/LICENSE) - [Project website](https://spotdl.readthedocs.io/en/latest/) - [README](https://github.com/spotDL/spotify-downloader/blob/master/README.md) - [Releases](https://github.com/spotDL/spotify-downloader/releases) - [spotDL/spotify-downloader on GitHub](https://github.com/spotDL/spotify-downloader) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/spotdl-spotify-downloader