spotDL — Download Spotify Music from the Command Line

Introduction

spotDL finds songs from Spotify playlists and albums on YouTube and downloads them with correct metadata, album art, and lyrics. It bridges the gap between Spotify's catalog and offline listening without needing a premium subscription.

What spotDL Does

• Downloads individual tracks, albums, playlists, and artist discographies from Spotify links
• Automatically matches Spotify tracks to YouTube audio sources
• Embeds album art, lyrics, and ID3 metadata into downloaded files
• Supports output formats including MP3, FLAC, OGG, OPUS, and M4A
• Provides a built-in web UI for browser-based downloading

Architecture Overview

spotDL uses the Spotify Web API to fetch track metadata and playlist information, then searches YouTube Music for matching audio. It downloads audio via yt-dlp, converts it with FFmpeg, and embeds metadata using mutagen. The matching algorithm scores candidates by title, artist, and duration similarity.

Self-Hosting & Configuration

• Requires Python 3.8+ and FFmpeg installed on the system
• Install via pip: pip install spotdl or use the Docker image
• Configure output format with --output-format mp3 or --output-format flac
• Set download directory with --output "{artist}/{album}/{title}.{output-ext}"
• Launch the web UI with spotdl web for a browser-based interface

Key Features

• Syncs playlists so only new or changed tracks are re-downloaded
• Multi-threaded downloads for faster batch processing
• Built-in web interface with drag-and-drop Spotify link support
• Pre-built binaries available for Windows, macOS, and Linux
• Preserves playlist ordering and folder structure

Comparison with Similar Tools

• yt-dlp — General-purpose video/audio downloader; spotDL adds Spotify metadata matching
• Deemix — Downloads from Deezer; spotDL targets Spotify via YouTube
• Zotify — Direct Spotify stream ripper; spotDL uses YouTube as the audio source
• savify — Similar concept but less actively maintained than spotDL

FAQ

Q: Does spotDL download directly from Spotify? A: No. It reads metadata from Spotify and downloads the matching audio from YouTube.

Q: What audio quality can I expect? A: Quality depends on the YouTube source, typically up to 256 kbps AAC or equivalent.

Q: Can I sync an entire library? A: Yes. Use spotdl sync with a playlist URL to keep a local folder in sync.

Q: Is FFmpeg required? A: Yes. FFmpeg handles audio conversion and is required for all output formats.

Sources

• https://github.com/spotDL/spotify-downloader
• https://spotdl.readthedocs.io/