Using yt-dlp to Search and Download Music from the Command Line
If you've ever wanted to grab a specific song without hunting down a URL first, yt-dlp has a built-in search feature that handles it for you. This will walk you through the basics.
What is yt-dlp?
yt-dlp is a command line tool for downloading audio and video from YouTube and hundreds of other sites. Most people use it by pasting in a URL, but it also has a powerful search function that lets you find and download content in a single command.
Basic Search Syntax
The search prefix is ytsearch followed by the number of results you want, a colon, and then your search term. For example, to find the top 5 results for classic country music:
If you only want one result, use ytsearch1:
Searching for a Specific Song
Include the artist name and song title for best results. YouTube's search is good enough that the first result is usually what you want. Before downloading anything, it's a good habit to verify that yt-dlp found the right track:
The -x Flag — Audio Only
The -x flag tells yt-dlp to give you audio only. Depending on what the site offers, it will either download an audio-only stream directly, or download the video, extract the audio, and then delete the video file automatically. Either way, you end up with just the audio file. Combined with --audio-format mp3, the result is a clean MP3:
If you want to keep the original video file in addition to the extracted audio, add the -k flag:
Tips for Better Search Results
Adding the word "official" to your search term helps when you want the artist's official upload rather than a cover or live version:
Adding "audio" or "lyrics" to the search term helps avoid live performances when you want the studio recording:
Downloading Multiple Results at Once
You can grab several results in one shot by increasing the number after ytsearch. This is handy for pulling down a few tracks from an artist:
To cap how many files actually get downloaded from a larger search pool, use --max-downloads:
Getting Search Results in JSON for Scripting
If you want to process search results in a script, the -j flag dumps each result as a JSON object, one per line. This is useful for feeding titles or URLs into another tool:
Other Search Prefixes
YouTube isn't the only platform yt-dlp can search. A few other useful prefixes are ytmsearch for YouTube Music, scsearch for SoundCloud, and yvsearch for Yahoo Video. The syntax is the same as ytsearch:
The search feature in yt-dlp is one of those things that once you start using it, you wonder how you got along without it. No more copying URLs from the browser — just describe what you want and let the tool find it. The more specific your search string, the better your results will be.
If you've ever wanted to grab a specific song without hunting down a URL first, yt-dlp has a built-in search feature that handles it for you. This will walk you through the basics.
What is yt-dlp?
yt-dlp is a command line tool for downloading audio and video from YouTube and hundreds of other sites. Most people use it by pasting in a URL, but it also has a powerful search function that lets you find and download content in a single command.
Basic Search Syntax
The search prefix is ytsearch followed by the number of results you want, a colon, and then your search term. For example, to find the top 5 results for classic country music:
Code:
yt-dlp "ytsearch5:classic country music"
If you only want one result, use ytsearch1:
Code:
yt-dlp "ytsearch1:Keith Whitley When You Say Nothing At All"
Searching for a Specific Song
Include the artist name and song title for best results. YouTube's search is good enough that the first result is usually what you want. Before downloading anything, it's a good habit to verify that yt-dlp found the right track:
Code:
yt-dlp --get-title "ytsearch1:Tim McGraw Live Like You Were Dying"
The -x Flag — Audio Only
The -x flag tells yt-dlp to give you audio only. Depending on what the site offers, it will either download an audio-only stream directly, or download the video, extract the audio, and then delete the video file automatically. Either way, you end up with just the audio file. Combined with --audio-format mp3, the result is a clean MP3:
Code:
yt-dlp -x --audio-format mp3 "ytsearch1:Don Williams Tulsa Time"
If you want to keep the original video file in addition to the extracted audio, add the -k flag:
Code:
yt-dlp -x -k --audio-format mp3 "ytsearch1:Don Williams Tulsa Time"
Tips for Better Search Results
Adding the word "official" to your search term helps when you want the artist's official upload rather than a cover or live version:
Code:
yt-dlp -x --audio-format mp3 "ytsearch1:Keith Whitley Don't Close Your Eyes official"
Adding "audio" or "lyrics" to the search term helps avoid live performances when you want the studio recording:
Code:
yt-dlp -x --audio-format mp3 "ytsearch1:Don Williams I Believe In You audio"
Downloading Multiple Results at Once
You can grab several results in one shot by increasing the number after ytsearch. This is handy for pulling down a few tracks from an artist:
Code:
yt-dlp -x --audio-format mp3 "ytsearch5:Tim McGraw"
To cap how many files actually get downloaded from a larger search pool, use --max-downloads:
Code:
yt-dlp --max-downloads 3 -x --audio-format mp3 "ytsearch10:soft rock 70s"
Getting Search Results in JSON for Scripting
If you want to process search results in a script, the -j flag dumps each result as a JSON object, one per line. This is useful for feeding titles or URLs into another tool:
Code:
yt-dlp -j "ytsearch5:Keith Whitley"
Other Search Prefixes
YouTube isn't the only platform yt-dlp can search. A few other useful prefixes are ytmsearch for YouTube Music, scsearch for SoundCloud, and yvsearch for Yahoo Video. The syntax is the same as ytsearch:
Code:
yt-dlp -x --audio-format mp3 "scsearch1:Don Williams Gentle On My Mind"
The search feature in yt-dlp is one of those things that once you start using it, you wonder how you got along without it. No more copying URLs from the browser — just describe what you want and let the tool find it. The more specific your search string, the better your results will be.

