Spotify selects the songs; YouTube supplies the audio
spotDL finds songs from Spotify playlists on YouTube and downloads them with metadata. Its README also documents album artwork and lyrics. This makes it a candidate for command-line users who want local files based on playlist selections and are willing to check the recordings.
The source distinction matters when you need a particular release or edition. Spotify metadata attached to a YouTube download does not establish that the audio is the recording you wanted. The supplied sandbox record contains no listening comparison or matching-accuracy assessment.
The usage guide documents manual pairing through the quoted argument "YouTubeURL|SpotifyURL". This lets you specify a YouTube source alongside Spotify metadata. That option was not exercised in the measured run.
What happened when we ran it
Our sandbox install succeeded in 19 seconds and the build step succeeded in 1 second at commit 58ced9a on November 7, 2026. The record lists 88 dependencies and 165 MB on disk. The test command exited 1 after 7 seconds, recording zero passed, zero failed assertions and 200 collection/setup errors. Zero failed assertions does not make that a successful test run.
The supplied tail names cases in tests/web/test_api.py, including settings updates and rejection of invalid format, bitrate and thread values. Pytest's summary reports one expected failure, seven warnings and 200 errors in 0.69 seconds. That summary and the outer 7-second step measure different scopes. Without the underlying exceptions, the tail cannot establish whether a package, runtime or network condition caused the errors. It also does not establish that the browser interface itself is broken.
The configured sandbox had 3 CPUs and 8 GB RAM, with image label ghcr.io/astral-sh/uv:python3.12-bookworm. Actual runtime and operating-system versions require the raw toolchain logs. The scan recorded 194 files, approximately 19,414 source lines and a 21.6 MB checkout. It found six CI workflows, a Dockerfile, a Compose file and a tests directory. These observations do not verify container operation. Pip-audit reported zero known vulnerabilities, without establishing application security or download reliability.
Check external tools and account access
The README recommends installing the Python package and requires FFmpeg. It documents spotdl --download-ffmpeg for a copy in the spotDL installation directory. It also strongly recommends Deno because some YouTube videos require it through yt-dlp, and provides spotdl --download-deno. These are upstream instructions, not commands verified by this review.
The usage guide requires --user-auth for liked songs and defines that option as Spotify login using OAuth. It also documents client-ID, client-secret and authorization-token options, plus a cookie-file option for YouTube Music account access. Their presence does not establish that every public playlist needs custom application credentials. Authentication, cookie handling and completed downloads remain unverified in the measured run.
The guide warns that converting to a higher bitrate can produce a larger file without a significant quality change. No encoding-quality measurement accompanies this review. Check the recording before treating an output setting as a quality improvement.
Synchronization deletes removed tracks by default, with an option to keep them
The README describes sync as downloading playlist additions and deleting songs removed from the playlist. The usage guide qualifies that default: --sync-without-deleting preserves songs that are no longer in the query.
For an existing sync file named playlist.spotdl, the documented command pattern is:
spotdl sync "playlist.spotdl" --sync-without-deleting
This example assumes the sync file already exists. The guide documents initialization with spotdl sync [query] --save-file [fileName] and requires the filename to end in .spotdl. Neither synchronization mode nor these commands were exercised in the measured run.
Choose the mode according to what a playlist edit should mean locally. Default synchronization suits a directory intended to mirror the current playlist. If removed playlist tracks should remain, the documented preservation option is relevant. Use a dedicated directory for a trial and keep files you intend to preserve elsewhere until you have checked the behavior in your own workflow. This is a precaution based on the documented deletion behavior, not a measured guarantee about deletion boundaries.
The README says the web interface only supports downloading individual songs. Readers who need playlist operations should assess the command-line workflow rather than assume the browser interface provides it.
What the documentation supports
Documentation receives 4/5 on an editorial scale: 1 means no actionable instructions, 2 means isolated instructions with major workflow gaps, 3 means a usable route with gaps, 4 means the reviewed documents explain prerequisites, command patterns and consequential options, and 5 additionally requires those reviewed workflows to be independently corroborated.
The README and usage guide explain FFmpeg, Deno, account options, synchronization initialization and the option to preserve removed tracks. That supports 4/5 for the reviewed documentation, while the absence of reproduced download and synchronization workflows prevents 5/5. This score does not establish adoption, compatibility or operational reliability. Setup ease, support capacity and production maturity remain unassessed.
Choose an alternative according to the job
yt-dlp is a command-line audio/video downloader. Consider it when you already know the source URL and want to select the recording yourself. There is no comparative download-success measurement in the supplied record.
Beets catalogs a music collection and improves its metadata. Consider it when the files already exist and organizing the collection is the main task.
For a spotDL trial, choose material you are authorized to download, check the recording and tags, and decide whether removed playlist tracks should remain locally before using synchronization.