Skip to main content

Download your Spotify playlists and songs along with album art and metadata

Project description



Download your Spotify playlists and songs along with album art and metadata

MIT License pypi version GitHub commits since latest release (by date) pypi downloads Contributors Discord

The fastest, easiest, and most accurate command-line music downloader


What spotDL does

  1. Downloads music from YouTube as an MP3 file
  2. Applies basic metadata gathered from Spotify such as:
    • Track Name
    • Track Number
    • Album
    • Album Cover
    • Genre
    • and more!


spotDL is being redesigned! This means we are currently not accepting new feature requests. You can talk to us on our Discord if there is anything further.


  • Python 3.6.1 or above (added to PATH)
  • FFmpeg 4.2 or above (added to PATH)

YouTube Music must be available in your country for spotDL to work. This is because we use YouTube Music to filter search results. You can check if YouTube Music is available in your country, by visiting YouTube Music.


Installing FFmpeg

Installing spotDL

  • Recommended Stable Version:

    pip install spotdl
  • Dev Version: (NOT STABLE)

    pip install

If you have trouble installing spotdl take a look at the extended installation guide here or ask for help in our discord server

On Termux

curl -L | sh


There is an Arch User Repository (AUR) package for spotDL.


  • To download a song, run

    spotdl [trackUrl]


  • To download an album, run

    spotdl [albumUrl]


  • To download a playlist, run

    spotdl [playlistUrl]


  • To download all songs from an artist run

    spotdl [artistUrl]


  • To search for and download a song, run, with quotation marks

    spotdl '[songQuery]'


    spotdl 'The Weeknd - Blinding Lights'

    Note: This is not accurate and often causes errors.

  • To resume a failed/incomplete download, run

    spotdl [pathToTrackingFile]


    spotdl 'The Weeknd - Blinding Lights.spotdlTrackingFile'

    Note: .spotdlTrackingFiles are automatically created when a download starts and deleted on completion

  • You can queue up multiple download tasks by separating the arguments with spaces

    spotdl [songQuery1] [albumUrl] [songQuery2] ... (order does not matter)


    spotdl 'The Weeknd - Blinding Lights' ...

    Note: spotDL downloads up to 4 songs in parallel, so for a faster experience, download albums and playlist, rather than tracks.

  • To download youtube video with metadata from spotify, run

    spotdl "YouTubeURL|SpotifyURL"


    spotdl "|"

    Note: Urls have to be separated with | and quoted properly ex. "YouTubeURL|SpotifyUrl"

  • To download songs with different output format run

    spotdl [songUrl] --output-format mp3/m4a/flac/opus/ogg/wav


    spotdl [songUrl] --output-format opus
  • To use ffmpeg binary that is not on PATH run

    spotdl [songUrl] --ffmpeg path/to/your/ffmpeg.exe


    spotdl [songUrl] --ffmpeg C:\ffmpeg\bin\ffmpeg.exe
  • To generate .m3u file for each playlist run

    spotdl [playlistUrl] --m3u


      spotdl --m3u
  • To use youtube instead of youtube music run

    spotdl [songUrl] --use-youtube


      spotdl --use-youtube
  • To manually choose a lyrics provider, run

      spotdl [songUrl] --lyrics-provider lyrics_provider

    available lyrics providers:

    • genius
    • musixmatch


      spotdl --lyrics-provider genius
  • To change number of threads used when downloading songs run

    spotdl [songUrl] --dt [number]


    spotdl --dt 8
  • To change number of threads used when searching for songs run

    spotdl [songUrl] --st [number]


    spotdl --st 8
  • To ignore your ffmpeg version run

    spotdl [songUrl] --ignore-ffmpeg-version
  • To use path template

    spotdl [songUrl] --path-template 'template'


    spotdl --path-template '{artist}/{album}/{title} - {artist}.{ext}'

    possible values:

    • {artist}
    • {artists}
    • {title}
    • {album}
    • {ext}
    • {playlist}

pipx Isolated Environment Alternative

For users who are not familiar with pipx, it can be used to run scripts without installing the spotDL package and all the dependencies globally with pip. (Effectively skipping over the spotDL Installation step)

First, you will need to install pipx by running:

python3 -m pip install --user pipx
python3 -m pipx ensurepath

Next, you can jump directly to running spotDL with:

pipx run spotdl ...

Contributor Guide

Interested in contributing? Check out our to find resources around contributing along with a guide on how to set up a development environment.




  1. @ritiek for creating and maintaining spotDL for 4 years
  2. @rocketinventor for figuring out YouTube Music querying
  3. @MikhailZex for, never mind...



Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

spotdl-3.9.6.tar.gz (42.8 kB view hashes)

Uploaded source

Built Distribution

spotdl-3.9.6-py3-none-any.whl (49.5 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page