{"id":24637,"library":"spotdl","title":"spotDL - Spotify Downloader","description":"spotDL downloads Spotify playlists and songs with album art and metadata. Version 4.4.4 requires Python <3.15,>=3.10. It uses yt-dlp or other sources to fetch audio. Releases are irregular but frequent.","status":"active","version":"4.4.4","language":"python","source_language":"en","source_url":"https://github.com/spotDL/spotify-downloader","tags":["spotify","downloader","music","cli"],"install":[{"cmd":"pip install spotdl","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"Required for audio processing; must be installed separately (not pip).","package":"ffmpeg","optional":false},{"reason":"Used as the default downloader for audio extraction from YouTube.","package":"yt-dlp","optional":false}],"imports":[{"note":"Main class for programmatic use.","symbol":"SpotDL","correct":"from spotdl import SpotDL"},{"note":"Running directly as 'spotdl' may not work if not installed in PATH; use 'python -m spotdl'.","wrong":"spotdl (without module invocation)","symbol":"__main__","correct":"python -m spotdl"}],"quickstart":{"code":"python -m spotdl 'https://open.spotify.com/track/4cOdK2wGLETKBW3PvgPWqT' --output '{artist} - {title}.{ext}'","lang":"python","description":"Download a single track by URL. Ensure Spotify credentials are set via environment variables SPOTIFY_CLIENT_ID and SPOTIFY_CLIENT_SECRET, or use OAuth."},"warnings":[{"fix":"Use 'from spotdl import SpotDL' and instantiate the class.","message":"In version 4.x, the CLI and API were restructured. Old imports like 'from spotdl import download' no longer work.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Install ffmpeg via your package manager (e.g., 'sudo apt install ffmpeg' on Ubuntu, 'brew install ffmpeg' on macOS).","message":"ffmpeg must be installed separately on your system. Without it, spotdl will fail silently or produce corrupted files.","severity":"gotcha","affected_versions":"all"},{"fix":"Use '--save-file' with appropriate format instead.","message":"The old '--write-m3u' flag is deprecated and may be removed in future versions.","severity":"deprecated","affected_versions":">=4.2.0"},{"fix":"Set environment variables: export SPOTIFY_CLIENT_ID='your_id'; export SPOTIFY_CLIENT_SECRET='your_secret'.","message":"Spotify API requires valid OAuth credentials. Without setting SPOTIFY_CLIENT_ID and SPOTIFY_CLIENT_SECRET, downloads will fail with 401 errors.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Run 'pip install spotdl' in the correct environment. Ensure you are using the same Python interpreter that spotdl was installed in.","cause":"spotdl is not installed or not found in the current Python environment.","error":"ModuleNotFoundError: No module named 'spotdl'"},{"fix":"Use '--output' with placeholders like '{artist} - {title}.{ext}'.","cause":"The '--format' flag was removed in v4.x; the output format is now specified via '--output'.","error":"spotdl: error: unrecognized arguments: --format"},{"fix":"Run 'pip install yt-dlp'.","cause":"yt-dlp is not installed.","error":"No module named 'yt_dlp'"},{"fix":"Install ffmpeg: on Ubuntu/Debian 'sudo apt install ffmpeg', on macOS 'brew install ffmpeg', on Windows download from ffmpeg.org.","cause":"ffmpeg is not installed on the system PATH.","error":"ffmpeg not found. Please install ffmpeg."},{"fix":"Re-authenticate by running 'spotdl --auth' or set SPOTIFY_CLIENT_ID and SPOTIFY_CLIENT_SECRET environment variables.","cause":"OAuth token is stale or credentials are missing.","error":"spotify token expired or invalid"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}