spotDL is a command-line tool that bridges Spotify and YouTube Music to download audio locally. Instead of downloading directly from Spotify (which is not possible), it extracts metadata from Spotify tracks and matches them against YouTube Music sources to retrieve audio files.

On macOS, installation is straightforward using pipx, but users often encounter runtime issues—most commonly failures in YouTube Music search resolution. This guide covers both setup and troubleshooting so you can reliably use spotDL in real-world conditions.

macOS prerequisite (IMPORTANT)

Before installing spotDL, you must install Homebrew (brew).

Homebrew is the most widely used package manager for macOS, allowing you to easily install, update, and manage open-source software and developer tools such as Python, FFmpeg, and pipx from the command line.

Step 1 — Install Homebrew

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

This command downloads and executes the official Homebrew installation script directly from the Homebrew GitHub repository. The installer guides you through the initial setup and configures Homebrew on your Mac, making it the recommended and officially supported installation method.

For more information, visit the Homebrew Installation Guide⁠ or browse the Homebrew installer source code on GitHub⁠.

Restart terminal (or reload shell)

$ source ~/.zshrc
or
$ source ~/.bashrc

or simply restart Terminal.

Why this is required

Without Homebrew:

• you cannot install pipx
• you cannot install ffmpeg
• you cannot properly manage Python tools on macOS

So everything in this stack depends on it:

Homebrew → Python → pipx → spotDL

After installing brew, your system PATH must update:

Step 2 — Install dependencies (after brew)

This step prepares your system with the required tools so macOS can properly run and manage Python-based CLI applications in isolated environments.

$ brew install python ffmpeg pipx

This installs the core tools needed for the workflow:

• python → runs spotDL and manages packages
• ffmpeg → converts and processes audio files (required for downloads) –without FFmpeg, audio conversion will fail.
• pipx → installs Python CLI apps in isolated environments (like spotDL) without affecting system Python

Then:

$ pipx ensurepath

This command configures your shell so that pipx-installed apps (like spotdl) are available globally in your terminal by adding ~/.local/bin to your PATH.

Step 3 — Install spotDL

With the prerequisites installed and your environment configured, you’re now ready to install spotDL.

$ pipx install spotdl

The following command installs spotDL in an isolated environment managed by pipx, making it available as a global command without modifying your system Python installation.

Verify:

$ spotdl --version

Step 4 — Basic usage

Once spotDL is installed, you can download a track by providing its Spotify URL. spotDL retrieves the track’s metadata from Spotify, searches for the best matching audio source on YouTube Music, and downloads it to your local machine.

$ spotdl https://open.spotify.com/track/URL

or

$ spotdl "Artist - Song Name"

Step 5 — Downloading a Spotify Playlist

Downloading an entire playlist is just as simple as downloading a single track. Instead of providing a track URL, pass the Spotify playlist URL to spotdl. The application will automatically process every song in the playlist, search for the best available match on YouTube Music, and download each track while preserving metadata such as the title, artist, album, cover artwork, and track number whenever possible.

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

Depending on the size of the playlist and your internet connection, the download may take several minutes to complete. During the process, spotDL displays the status of each track, allowing you to monitor its progress and identify any songs that could not be matched automatically.

Common issue: YouTube Music returns no results.

If you see:

“No usable results found”

This is not an installation issue. It usually means:

• YouTube Music search is rate-limited or blocked
• Region restrictions affect results
• Spotify metadata doesn’t match YouTube titles exactly

Fix strategies

1. Retry using plain text search

$ spotdl "Song Name official audio"

2. Use VPN (regional filtering issue)

Some regions return incomplete YouTube Music results.

3. Update spotDL

$ pipx upgrade spotdl

4. Use alternative query formats

Sometimes Spotify URLs fail, but manual queries work better.

That wraps up this step-by-step guide to installing and using spotDL on macOS. As you’ve seen, the setup process is straightforward once the required tools are in place. spotDL is powerful but not a direct Spotify downloader—it depends entirely on YouTube Music matching. Once installed properly via pipx and paired with FFmpeg, most issues come from search mismatches or regional limitations rather than the tool itself. For best reliability, treat spotDL as a metadata-driven downloader and use fallback search strategies when automatic resolution fails.

For additional playlist options, output customization, and advanced download settings, run:

$ spotdl --help

This command lists all available options, allowing you to customize output directories, file naming, audio formats, metadata handling, and much more.

Stay tuned for more.