spotDL Files

Required Action & Breaking Changes

• We strongly recommend installing Deno. Some yt-dlp downloads may fail without a JavaScript runtime.

• Run spotdl --download-deno, or install Deno system-wide using the official Deno installation guide.

• Due to Spotify API changes, spotDL now defaults to the lighter SpotipyFree library, which has reduced functionality compared with the official Spotify API.

• If you have Spotify Premium and provide a client ID and client secret, pass --use-official-api to use the official API.

• The default SpotipyFree client does not support authenticated library shortcuts/functions such as saved, all-user-playlists, all-saved-playlists, all-user-followed-artists, and all-user-saved-albums. Use --user-auth with the official API for these. We plan to restore support for these shortcuts soon.

• The youtube audio provider has been migrated from pytube to yt-dlp.

• This does not change the default youtube-music provider.

• Docker images now run as a non-root user and Docker Compose now uses a named spotdl_music volume by default.

• If you bind-mount a host directory to /music, make sure it is writable by the container UID/GID.

What's Changed

• Replaced Spotipy with a non-API library by @TzurSoffer in https://github.com/spotDL/spotify-downloader/pull/2626
• Update search_all to include verified results and fix SpotipyFree initialization by @TzurSoffer in https://github.com/spotDL/spotify-downloader/pull/2665
• Fix/revert search fallback, recommending Deno instead by @Silverarmor in https://github.com/spotDL/spotify-downloader/pull/2672
• Add optional Deno downloader for yt-dlp-ejs support by @Silverarmor in https://github.com/spotDL/spotify-downloader/pull/2650
• Migrate YouTube audio provider from pytube to yt-dlp by @Pobitro-B in https://github.com/spotDL/spotify-downloader/pull/2524
• Retry YouTube Music searches with a fresh client by @Silverarmor in https://github.com/spotDL/spotify-downloader/pull/2671
• Fix YouTube not downloading by @antonpup in https://github.com/spotDL/spotify-downloader/pull/2564
• Support new Spotify API response format (track -> item) by @BillionClaw in https://github.com/spotDL/spotify-downloader/pull/2628
• Get items from Spotify response JSON with .get to avoid KeyError by @igoiglesias in https://github.com/spotDL/spotify-downloader/pull/2656
• Fix songs with missing genres in Spotify API responses by @BillionClaw in https://github.com/spotDL/spotify-downloader/pull/2629
• Add Docker support for running as a non-root user by @aycsi in https://github.com/spotDL/spotify-downloader/pull/2489
• Pin Docker base image to python:3.13-alpine and skip dev dependencies by @CatTail in https://github.com/spotDL/spotify-downloader/pull/2658
• Sanitize list names before formatting M3U filenames by @tomdec in https://github.com/spotDL/spotify-downloader/pull/2560
• Replace tmpdir with tmp_path in tests by @dotlambda in https://github.com/spotDL/spotify-downloader/pull/2550

New Contributors

• @BillionClaw made their first contribution in https://github.com/spotDL/spotify-downloader/pull/2629
• @CatTail made their first contribution in https://github.com/spotDL/spotify-downloader/pull/2658
• @TzurSoffer made their first contribution in https://github.com/spotDL/spotify-downloader/pull/2626
• @igoiglesias made their first contribution in https://github.com/spotDL/spotify-downloader/pull/2656
• @antonpup made their first contribution in https://github.com/spotDL/spotify-downloader/pull/2564
• @tomdec made their first contribution in https://github.com/spotDL/spotify-downloader/pull/2560
• @Pobitro-B made their first contribution in https://github.com/spotDL/spotify-downloader/pull/2524
• @aycsi made their first contribution in https://github.com/spotDL/spotify-downloader/pull/2489

Full Changelog: https://github.com/spotDL/spotify-downloader/compare/v4.4.4...v4.5.0