Please note that this wiki page is for the deprecated v2 of spotDL. You should update to v3.

---

Installation

Debian-like GNU/Linux & macOS

spotify-downloader is on PyPI! You can install it using pip. However, note that the program only supports Python 3.6+.

$ pip install -U spotdl

IMPORTANT: if you have both Python 2 and 3 installed, the pip command could invoke an installation for Python 2. To see which Python version pip refers to, try pip -V. If it turns out pip is your Python 2 pip, try pip3 install -U spotdl instead.

You'll also need to install FFmpeg for conversion.

Debian-like GNU/Linux:

$ sudo apt-get install ffmpeg

macOS:

$ brew install ffmpeg --with-libmp3lame --with-libass --with-opus --with-fdk-aac

If FFmpeg does not install correctly, you may have to build it from source. For more info see https://trac.ffmpeg.org/wiki/CompilationGuide.

Windows

Assuming you have Python 3.6 already installed and in PATH.

Open cmd and type pip install -U spotdl to install spotify-downloader. The same note about pip as for Debian, Ubuntu, Linux & Mac applies.

You'll also need to download zip file for FFmpeg from https://ffmpeg.zeranoe.com/builds/. Extract it and then place all the .exe files in a directory included in your PATH variable. C:\Windows\System32\ usually works fine.

NOTE: In case placing ffmpeg.exe in System32 directory doesn't work, then you need to manually add the FFmpeg directory to PATH. See this on how to do that: https://docs.alfresco.com/4.2/tasks/fot-addpath.html or https://www.youtube.com/watch?v=qjtmgCb8NcE.

Docker Image

We also provide the latest docker image on DockerHub.

• Pull (or update) the image with docker pull ritiek/spotify-downloader.

• Run it with docker run --rm -it -v $(pwd):/music ritiek/spotify-downloader <arguments>.

• The container will download music and write tracks in your current working directory.

Changing the root directory where the tracks get downloaded to any different than the current directory tree with -f argument will NOT work with Docker containers.

Example - Downloading a Playlist

$ docker run --rm -it -v $(pwd):/music ritiek/spotify-downloader -p https://open.spotify.com/user/nocopyrightsounds/playlist/7sZbq8QGyMnhKPcLJvCUFD
$ docker run --rm -it -v $(pwd):/music ritiek/spotify-downloader -l ncs-releases.txt

Vagrant Box

@csimpi has posted very detailed instructions here. Quoting them so they don't get lost:

Installing Virtualbox and Vagrant

You will need Vagrant from http://vagrantup.com, and virtualbox from https://www.virtualbox.org/.

Setting up Vagrant virtual machine

Make an empty folder, this folder will contain your vagrant machine. Step into the folder and run the following commands:

vagrant init ubuntu/trusty64
vagrant up

Log in to the installed linux instance (password: vagrant)

vagrant ssh

Run the following commands:

sudo apt-get update
sudo apt-get -y upgrade
sudo apt-get install -y python3-pip
sudo apt-get install build-essential libssl-dev libffi-dev python-dev
sudo apt-get install git

cd ~
git clone https://github.com/ritiek/spotify-downloader
cd spotify-downloader
pip3 install -U -r requirements.txt
sudo apt-get install ffmpeg

You will get a ready-to-use environment and installed version of the awesome ritiek/spotify-downloader library.

You can link your inside download folder to your physical hard drive, so you will be able to get your downloaded files directly from your main operation system, don't need to be logged in to the Vagrant virtual machine, your downloaded files will be there on your computer, and the library won't make any footprint in your system. That's cool, isn't it?

Instructions for Downloading Songs

Download by Name

For example

• We want to download Fade by Alan Walker, run the command:

$ spotdl --song "alan walker fade"

• The script will automatically look for the best matching song and download it in the folder Music/ placed in the root directory of the code base.

• It will now convert the song to an mp3 and try to fix meta-tags and album-art by looking up on Spotify.

• The --song parameter can also accept multiple tracks like so:

$ spotdl --song "alan walker fade" "tobu candyland"

Download by Spotify Link (Recommended for full-metadata support)

For example

• We want to download the same song (i.e: Fade by Alan Walker) but using Spotify Link this time that looks like https://open.spotify.com/track/2lfPecqFbH8X4lHSpTxt8l, you can copy it from your Spotify desktop or mobile app by right clicking or long tap on the song and copy HTTP link.

• Run:

$ spotdl --song https://open.spotify.com/track/2lfPecqFbH8X4lHSpTxt8l

It should download Fade by Alan Walker.

• Just like before, it will again convert the song to an mp3 but since we used a Spotify HTTP link, the script is guaranteed to fetch the correct meta-tags and album-art.

Download by File

For example

• We want to download Fade by Alan Walker, Sky High by Elektromania and Fire by Elektromania just using a single command.

Let's suppose, we have the Spotify link for only Fade by Alan Walker and Fire by Elektromania.

• Just make a list.txt anywhere on your drive and add all the songs you want to download, in our case it is

https://open.spotify.com/track/2lfPecqFbH8X4lHSpTxt8l
elektromania sky high
https://open.spotify.com/track/0fbspWuEdaaT9vfmbAZr1C

• Now pass --list=/path/to/list.txt to the script, i.e:

$ spotdl --list=/path/to/list.txt

and it will start downloading songs mentioned in list.txt.

• The script will remove the track from the list file once it gets downloaded with metadata applied, and then continue to the next track. So in case if you accidentally interrupt the download, you can always re-launch the same command back and the script will continue downloading the tracks from where it left off.

NOTE: Songs that are already downloaded will prompt you to overwrite or skip. This behaviour can be changed by passing --overwrite {prompt,skip,force}.

Download by Playlist Link

• You can copy the Spotify URL of the playlist and pass it in --playlist option. Note: This method works for public as well as private playlists.

For example:

$ spotdl --playlist https://open.spotify.com/user/nocopyrightsounds/playlist/7sZbq8QGyMnhKPcLJvCUFD

• The script will load all the tracks from the playlist into <playlist_name>.txt

• Run: spotdl --list=<playlist_name>.txt to download all the tracks (see #download-by-file for more info).

Download by Album Link

• You can copy the Spotify URL of the album and pass it in --album option.

For example

$ spotdl --album https://open.spotify.com/album/499J8bIsEnU7DSrosFDJJg

• The script will load all the tracks from the album into <album_name>.txt

• Run:

$ spotdl --list=<album_name>.txt

to download all the tracks (see #download-by-file for more info).

Download by Username

• You can also load songs using Spotify username if you don't have the playlist URL. (Open profile in Spotify, click on the three little dots below name, "Share", "Copy to clipboard", paste last numbers or text into command-line: https://open.spotify.com/user/0123456790)

• Try running

$ spotdl -u <your_username>

It will (only) show all your public playlists (which excludes collaborative and private playlists).

• Once you select the one you want to download, the script will load all the tracks from the playlist into <playlist_name>.txt.

• Run:

$ spotdl --list=<playlist_name>.txt

to download all the tracks (see #download-by-file for more info).

Download by Artist Link

• You can copy the Spotify URL of the artist and pass it in --all-albums option.

For example

$ spotdl --all-albums https://open.spotify.com/artist/1feoGrmmD8QmNqtK2Gdwy8

• The script will load all the tracks from artist's available albums into <artist_name>.txt

• Run:

$ spotdl --list=<artist_name>.txt

to download all the tracks (see #download-by-file for more info).

Download by YouTube Link

• You can copy the YouTube URL or ID of a video and pass it in -s option.

For example

• Run:

$ spotdl -s https://www.youtube.com/watch?v=lc4Tt-CU-i0

It should download 2SCOOPS by Donuts.

Available options

This page contains a complete list of all available options with description. For advanced usage of the program check out the Advanced usage wiki page.

usage: spotdl [-h]
              (-s SONG [SONG ...] | -l LIST | -p PLAYLIST | -a ALBUM | -aa ALL_ALBUMS | -u USERNAME)
              [--write-m3u] [-m] [-nm] [-ne] [--overwrite {prompt,force,skip}]
              [-q {worst,best}] [-i {m4a,automatic,opus}] [-o {m4a,mp3,flac}]
              [--write-to WRITE_TO] [-f OUTPUT_FILE] [--trim-silence]
              [-sf SEARCH_FORMAT] [-d] [-ns] [-sk SKIP_FILE]
              [-w WRITE_SUCCESSFUL_FILE] [-ll {INFO,WARNING,ERROR,DEBUG}]
              [-c CONFIG] [--remove-config] [-V]

Download and convert tracks from Spotify, Youtube, etc.

optional arguments:
  -h, --help            show this help message and exit
  -s SONG [SONG ...], --song SONG [SONG ...]
                        download track(s) by spotify link or name (default:
                        None)
  -l LIST, --list LIST  download tracks from a file (WARNING: this file will
                        be modified!) (default: None)
  -p PLAYLIST, --playlist PLAYLIST
                        load tracks from playlist URL into <playlist_name>.txt
                        or if `--write-to=<path/to/file.txt>` has been passed
                        (default: None)
  -a ALBUM, --album ALBUM
                        load tracks from album URL into <album_name>.txt or if
                        `--write-to=<path/to/file.txt>` has been passed
                        (default: None)
  -aa ALL_ALBUMS, --all-albums ALL_ALBUMS
                        load all tracks from artist URL into <artist_name>.txt
                        or if `--write-to=<path/to/file.txt>` has been passed
                        (default: None)
  -u USERNAME, --username USERNAME
                        load tracks from user's playlist into
                        <playlist_name>.txt or if `--write-
                        to=<path/to/file.txt>` has been passed (default: None)
  --write-m3u           generate an .m3u playlist file with youtube links
                        given a text file containing tracks (default: False)
  -m, --manual          choose the track to download manually from a list of
                        matching tracks (default: False)
  -nm, --no-metadata    do not embed metadata in tracks (default: False)
  -ne, --no-encode      do not encode media using FFmpeg (default: False)
  --overwrite {prompt,force,skip}
                        change the overwrite policy (default: prompt)
  -q {worst,best}, --quality {worst,best}
                        preferred audio quality (default: best)
  -i {m4a,automatic,opus}, --input-ext {m4a,automatic,opus}
                        preferred input format (default: automatic)
  -o {m4a,mp3,flac}, --output-ext {m4a,mp3,flac}
                        preferred output format (default: mp3)
  --write-to WRITE_TO   write tracks from Spotify playlist, album, etc. to
                        this file (default: None)
  -f OUTPUT_FILE, --output-file OUTPUT_FILE
                        path where to write the downloaded track to, special
                        tags are to be surrounded by curly braces. Possible
                        tags: (default: {artist} - {track-name}.{output-ext})
  --trim-silence        remove silence from the start of the audio (default:
                        False)
  -sf SEARCH_FORMAT, --search-format SEARCH_FORMAT
                        search format to search for on YouTube, special tags
                        are to be surrounded by curly braces. Possible tags:
                        (default: {artist} - {track-name} lyrics)
  -d, --dry-run         show only track title and YouTube URL, and then skip
                        to the next track (if any) (default: False)
  -ns, --no-spaces      replace spaces in metadata values with underscores
                        when generating filenames (default: False)
  -sk SKIP_FILE, --skip-file SKIP_FILE
                        path to file containing tracks to skip (default: None)
  -w WRITE_SUCCESSFUL_FILE, --write-successful-file WRITE_SUCCESSFUL_FILE
                        path to file to write successful tracks to (default:
                        None)
  -ll {INFO,WARNING,ERROR,DEBUG}, --log-level {INFO,WARNING,ERROR,DEBUG}
                        set log verbosity (default: INFO)
  -c CONFIG, --config CONFIG
                        path to custom config.yml file (default:
                        /home/ritiek/.config/spotdl/config.yml)
  --remove-config       remove previously saved config (default: False)
  -V, --version         show program's version number and exit

FAQ

How to specify a custom folder where tracks should be downloaded?

If you don't want to download all the tracks into your current directory, you can use the -f option to specify another directory.

Example

$ spotdl -s "ncs - spectre" -f "/home/user/Happy-Music/"

This works with both relative and absolute paths.

If you do not specify a file naming scheme, a warning will be produced and the program will use the default naming scheme, which means the above command would automatically expand to:

$ spotdl -s "ncs - spectre" -f "/home/user/Happy-Music/{artist} - {track-name}.{output-ext}"

Where is my config.yml?

Check out Advanced-usage#config-file.

How to skip already downloaded tracks by default?

If there exists a track in your download directory with filename same as the one being downloaded,the tool will prompt on whether to skip downloaded the current track or overwrite the previously downloaded track. You can change this behaviour by passing one of prompt, skip, or force in the --overwrite argument.

Example

$ spotdl -l=/home/user/my_fav_tracks.txt --overwrite skip

This will automatically skip downloaded tracks which are already present in the download directory.

From where are the tracks being downloaded from? Is it directly from Spotify?

No. The download happens from YouTube. Spotify is only used as a source of metadata.

spotify-downloader typically follows the below process to download a Spotify track:

• Get the artist and track name of the track from Spotify

• Search for this track on YouTube

• Get lyrics for the track from Genius

• Downloads the audiostream from YouTube in an .opus or .webm format (or as specified in input format) and simuntaneously encodes it to an .mp3 format (or as specified in output format)

• Finally apply metadata from Spotify to this encoded track

The download bitrate is very low?

If there were a way to get better audio quality, someone would have already done it. Also see #499, #137, #52.

I get this youtube-dl error all of a sudden?

Also see #488, #484, #466, #433, #399, #388, #385, #341.

Usually youtube-dl devs have already published a fix on PyPI by the time you realize this error. You can update your youtube-dl installation with:

$ pip3 install youtube-dl -U

In case this still doesn't fix it for you and the above linked issues are not of any help either, feel free to open a new issue. It would be a good idea to bring this problem to light in the community.

I get this error: ssl.SSLError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed?

If you're on OS X, see https://stackoverflow.com/questions/42098126/mac-osx-python-ssl-sslerror-ssl-certificate-verify-failed-certificate-verify.

If you're still getting the same error, also try running:

$ pip3 install --upgrade certifi

For related OS X issues, see #125 #143 #214 #245 #443 #480 #515.

If you're on a Linux based distro, check out #480 for possible solutions.

The downloads used to work but now I get HTTP Error 429: Too Many Requests?

You probably have been downloading too many tracks (~1k) per day. This error should automatically go away after waiting for a while (some hours or even a day). See #560 for more information. If you want to keep downloading more without the wait, consider setting up/switching to a different proxy/VPN or anything that does not send your old IP address to YouTube. Rebooting your modem or restarting mobile data services sometimes helps too.

Advanced Usage

Config file

At first run, this tool will generate a config.yml and mention the location where it gets placed to. You can then modify this config.yml to override any default options.

This config.yml will ideally be written to:

• For Linux: ~/.config/spotdl/config.yml
• For Windows: C:\Users\<user>\AppData\Local\spotdl\config.yml.
• For macOS: ~/Library/Application Support/spotdl/config.yml

You can know the location where your config.yml is in with:

$ spotdl --help

and looking for something like this in the output:

  -c CONFIG, --config CONFIG
                        path to custom config.yml file (default:
                        /home/ritiek/.config/spotdl/config.yml)

Also note that config options are overridden by command-line arguments.

If you want to use custom .yml configuration instead of the default one, you can use -c/--config option, e.g. spotdl -s "ncs spectre" -c "/home/user/customConfig.yml"

Here's a sample config file depicting how it should look like:

spotify-downloader:
  dry_run: false
  input_ext: automatic
  log_level: INFO
  manual: false
  no_encode: false
  no_metadata: false
  no_spaces: false
  output_ext: mp3
  output_file: '{artist} - {track-name}.{output-ext}'
  overwrite: prompt
  quality: best
  search_format: '{artist} - {track-name} lyrics'
  skip_file: null
  spotify_client_id: 4fe3fecfe5334023a1472516cc99d805
  spotify_client_secret: 0f02b7c483c04257984695007a4a8d5c
  trim_silence: false
  write_successful_file: null
  write_to: null

Set custom YouTube search query

If you're not matching with correct tracks on YouTube, you can tweak the search query (search-format) in config.yml or on the command-line according to your needs. Currently the default search query is set to '{artist} - {track-name} lyrics'. You can specify other special tag attributes in curly braces too. The following tag attributes are supported:

• track-name
• artist
• album
• album-artist
• genre
• disc-number
• duration
• year
• original-date
• track-number
• total-tracks
• isrc
• track-id
• output-ext

For example:

$ spotdl -s https://open.spotify.com/track/4wX3QCU2hWtuPiv8GSakrz -sf "{artist} - {track-name} nightcore"

This will attempt to download the Nightcore version of the track.

Set custom filenames

You can also set custom filenames for downloaded tracks in your config.yml under output-file key or with -f option . By default, downloaded tracks are renamed to '{artist} - {track-name}.{output-ext}'. You can also create sub-directories with this option. Such as setting the output-file key to '{artist}/{track-name}.{output-ext}' will create a directory with the artist's name and download the matched track to this directory.

This option supports same tag attributes as in setting custom YouTube search queries.

For example:

$ spotdl -s https://open.spotify.com/track/4wX3QCU2hWtuPiv8GSakrz -f "{artist}/{album}/{track-name}.{output-ext}"

This will create a directory with the artist's name and another sub-directory inside with the album name and download the track here.

Using pipes

The --song argument supports reading input from STDIN. You can also write tracks to STDOUT in as they are being downloaded by passing -f -. Similarly, you can also write tracks from --playlist, --album, etc. to STDOUT by passing --write-to -.

• For example, reading "to-download" tracks from STDIN:

  $ echo "last heroes - eclipse" | spotdl -s -
  

  Multiple tracks must be separated with a line break character \n, such as:

  $ echo "last heroes - eclipse\n" "culture code - make me move" | spotdl -s -
  

• For example, to pipe a track to mpv player for it to play via STDOUT:

  $ spotdl -s "last heroes - eclipse" -f - | mpv -
  

  This will download, encode and pass the output to mpv for playing, in real-time. If you'd like to avoid encoding, pass --no-encode like so:

  $ spotdl -s "last heroes - eclipse" -f - --no-encode | mpv -
  

  Writing to STDOUT assumes --no-metadata and should display an appropriate warning.

Embedding spotdl in Python scripts

This will be documented soonish!

Maintaining a skip tracks file

You can keep a skip file to prevent the tracks present in skip from being downloaded again. This is faster than having the tool automatically check (which may sometimes also result in poor detection) whether a previous track with same filename has been already downloaded.

This skip file can be then passed to --skip-file parameter when downloading using --list parameter which will skip all the tracks mentioned in the skip file.

This maybe be useful with --write-successful-file parameter which writes the successfully downloaded tracks to the filename passed.

--skip-file and --write-successful-file parameters may also point to the same file.

For more info; see the relevant issue #296 and PR #386.

Apply metadata from a different track

You can download one track and apply metadata to this track from another track. -s accepts another track which can be used as a metadata source. This metadata source track needs to be separated using "::" from the track to be downloaded.

For example:

$ spotdl -s "nightcore janji heroes::janji heroes"

This will download the nightcore version of the track but the original track would be used for metadata. Similarly, one may also pass Spotify URIs or YouTube URLs (instead of search queries) in either of these two tracks.

Use a proxy server

To use a proxy server you can set the http_proxy and https_proxy environment variables, for example:

$ http_proxy=http://127.0.0.1:1080 https_proxy=https://127.0.0.1:1081 spotdl <arguments>

For a detailed explanation see #505 (comment).