spotDL Spotify Downloader

Music Sourcing

spotDL uses YouTube as the source for music downloads to avoid issues related to downloading directly from Spotify.

Audio Quality

spotDL is designed to always download the highest possible bitrate available on YouTube:

• Regular users: 128 kbps
• YouTube Music Premium users: 256 kbps

When providing a query (Spotify/YouTube URL), you can use specific prefixes to improve search accuracy for albums, playlists, or artists.

Query Prefixes:

• album:<name>
• playlist:<name>
• artist:<name>

You can mix these for better results.

Special Queries for User Data:

• saved: Download liked songs.
• all-user-playlists: Download all user playlists.
• all-saved-playlists: Download playlists the user has created.
• all-user-followed-artists: Download all user liked playlists.
• all-user-saved-albums: Download all user saved albums.

Manual Audio Matching: Use the format YouTubeURL|SpotifyURL to manually match a specific YouTube audio source to a Spotify track.

spotDL has a strict policy against automated contributions to prevent wasting maintainer time:

• Prohibited: Submitting AI-generated issues, pull requests, or feature requests. Using AI to generate code for PRs is not allowed. Submitting such requests will result in being blocked from the repository.
• Allowed: Using AI tools for proofreading, translating, or helping you understand an issue's content.
• Requirement: You must be able to explain every part of the code you submit and respond to questions regarding your fix.

The project is organized into several key sub-packages:

All submitted code must include documentation following these specific formats:

Functions

one-liner about function's purpose

### Args (optional)
- arg_name: description

### Returns (optional)
- return value description

### Errors (optional)
- known errors

### Notes (optional)
- notes if any

Classes

one-liner about class purpose

### Attributes
- attribute: description

### Notes (optional)
- notes if any

Modules/Packages (__init__)

At most 3 lines about module/package purpose

Optional usage example for module/package, preferably showcasing most commonly used functionality

Before reporting a bug, ensure you are on the latest version, check the bug tracker for existing reports, and verify it isn't an environment issue.

Important: Never report security vulnerabilities or sensitive bugs in public GitHub issues. Send these via Discord to Silverarmor (spotDL Discord Owner).

How to submit a good report:

1. Open a GitHub issue.
2. Explain the expected behavior vs. the actual behavior.
3. Provide reproduction steps (ideally a reduced test case/code).
4. Include context: Stack trace (Traceback), OS/Platform/Version, and relevant environment details (interpreter, runtime, etc.).

Termux

Use the dedicated installation script:

curl -L https://raw.githubusercontent.com/spotDL/spotify-downloader/master/scripts/termux.sh | sh

Arch Linux (AUR)

An AUR package is available at https://aur.archlinux.org/packages/spotdl.

The recommended installation method is via Python.

Prerequisites

• Windows: Install Visual C++ 2019 redistributable.
• Python: Version 3.10 - 3.14 must be installed and added to PATH.
• FFmpeg: Version 4.2 or above must be added to PATH.

Installation Steps

1. Verify Python installation: python -V (ensure v3.7 or greater).
2. Install spotDL using pip:

pip install spotdl

Note: On OSX/UNIX, use pip3 instead of pip and python3 instead of python.

You can launch a web-based user interface by running: spotdl web

By default, the Web UI downloads files to a special directory. To make the Web UI follow your configured --output directory, use the --web-use-output-dir option.

spotdl web --web-use-output-dir

spotDL uses a JSON configuration file to store settings. You can generate a new one or load an existing one.

Generate a config file: Use the --generate-config flag to create a new configuration file. Note that this will overwrite any existing config.

Config file locations:

• Windows: C:\Users\<user>\.spotdl\config.json
• Linux/macOS: ~/.spotdl/config.json

Using the config: Use the --config flag to explicitly point to a configuration file during an operation.

spotdl --generate-config
spotdl --config /path/to/config.json [operation] [query]

The recommended way to install spotDL is using pip. This allows for easy updates using the --upgrade flag.

To install:

pip install spotdl

To update:

pip install --upgrade spotdl

Note: On some systems, you may need to use pip3 instead of pip.

spotDL uses mkdocs to generate its documentation. You can build the static site or serve it locally for real-time previewing while editing.

# Build documentation
mkdocs build --strict

# Serve documentation locally
mkdocs serve