spotDL is a command-line tool that uses Spotify metadata to find matching audio on YouTube and download it locally. It can retrieve information such as song titles, artists, albums, and cover artwork.

Because spotDL relies on matching Spotify tracks with available YouTube audio, some downloads may fail due to search mismatches, unavailable recordings, or temporary service issues.

This guide covers installation, basic usage, and common troubleshooting steps on macOS.

Step 1 — Install Homebrew

Homebrew is a package manager for macOS that simplifies the installation of command-line tools.

If Homebrew is not already installed, open Terminal and run:

$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Follow the installer's instructions to complete the setup.

On Apple Silicon Macs, Homebrew is usually installed under /opt/homebrew; on Intel Macs, it is usually under /usr/local.

For additional information, consult the official Homebrew installation guide.

Step 2 — Install the dependencies

Install Python, FFmpeg, pipx, and Deno:

$ brew install python ffmpeg pipx deno

These tools serve different purposes:

• Python: Runs spotDL.
• FFmpeg: Processes and converts audio.
• pipx: Installs Python command-line applications in isolated environments.
• Deno: Supports certain YouTube download operations.

Next, configure pipx:

$ pipx ensurepath

If the commands are not immediately available, open a new Terminal window.

Verify the installations:

python3 --version
ffmpeg -version
pipx --version
deno --version

Step 3 — Install spotDL

Install spotDL using pipx:

$ pipx install spotdl

Verify the installation:

$ spotdl --version

If Terminal reports command not found, check your PATH configuration and reopen Terminal.

For detailed installation instructions, see the official spotDL documentation.

Step 4 — Download an individual track

To download a track, provide its Spotify URL:

$ spotdl download "https://open.spotify.com/track/TRACK_ID"

Replace TRACK_ID with the actual track ID or use the complete Spotify URL.

You can also search by artist and song title:

$ spotdl download "Artist - Song Name"

By default, downloaded files are saved in your current working directory. To organize your downloads, create a dedicated folder:

$ mkdir -p ~/Music/spotdl
$ cd ~/Music/spotdl

Run your spotDL commands from that directory.

Step 5 — Download a playlist

To download a Spotify playlist, provide its URL:

$ spotdl download "https://open.spotify.com/playlist/PLAYLIST_ID"

spotDL processes the playlist's tracks individually and attempts to find matching audio. It also preserves available metadata, including titles, artists, and album information.

Download times depend on the playlist size, your internet connection, and the availability of matching audio. Some tracks may fail even when the rest of the playlist downloads successfully.

Troubleshooting: YouTube search returns no results

A common error is:

No usable results found

This means spotDL could not find a suitable audio match. Possible causes include unavailable tracks, metadata mismatches, network problems, or temporary service restrictions.

Try the following solutions.

1. Use a text search

If a Spotify URL fails, search by artist and title:

$ spotdl download "Artist - Song Name official audio"

A more specific query may help spotDL find a suitable match.

2. Update spotDL

Update to the latest available version:

$ pipx upgrade spotdl

3. Check the dependencies

Verify that FFmpeg and Deno are available:

$ ffmpeg -version
$ deno --version

If either command fails, check its installation and PATH configuration.

4. Retry later

If multiple tracks fail unexpectedly, the problem may be temporary. Check your internet connection and retry after some time.

A VPN is not a guaranteed solution to regional restrictions or search failures.

Useful commands

For additional configuration options, run:

$ spotdl --help

Installing spotDL on macOS is straightforward with Homebrew and pipx. Once Python, FFmpeg, and the recommended supporting dependencies are configured, you can download individual tracks and process playlists using Spotify URLs or text searches.

Remember that spotDL does not download audio directly from Spotify. It uses Spotify metadata to find matching audio elsewhere, so successful downloads depend on source availability and compatibility with external services.

For further information, consult the official spotDL documentation.

Note: Download only content you have the necessary rights or permission to access, and respect applicable copyright laws and service terms.

Stay tuned for more.