Don't be afraid of the commands and lines on yt-dlp. This full guide is dedicated to newbies, covering installation to operation with step-by-step guides in plain words. And I know that the official GitHub page has the most comprehensive guide, but we don't have to read all of it from start to end. Thus, let's have a quick drive to get you familiar with yt-dlp in 10 minutes (5 minutes if you're a smart guy).
Starting Line: Installation & Update YT-DLP
As an actively maintained and powerful video downloading tool, yt-dlp not only can download YouTube videos, but it also supports hundreds of platforms, including Vimeo, and more. Besides, there are actually lots of ways to install yt-dlp on different devices. I picked the methods I experienced only, so that I can make the guide more obvious.
1. For Windows Users
Before you install it, you need Python installed first.
Now we are going to install yt-dlp. Check the steps below.
For updating yt-dlp on Windows, close the yt-dlp window running currently first, then you can download the latest yt-dlp.exe and simply overwrite your original yt-dlp.exe file, or update it with CMD by yt-dlp -U. If you installed yt-dlp with pip, the upgrade command is pip install -U yt-dlp. Enter this command in Command Prompt (CMD) or PowerShell, and yt-dlp will automatically download and replace itself with the latest version.
2. For Mac Users
Now we need an assistant called Homebrew, the most commonly used software management tool on Mac, making it very convenient to install many things.
You have 2 ways to get yt-dlp installed on your Mac devices now. You can do it with Homebrew, by the command brew install yt-dlp, or with pip (a package management tool for Python3) by the command pip3 install -U yt-dlp. And always remember to check the installation with yt-dlp --version.
3. For Linux Users
There are many Linux distributions; the most common ones are Ubuntu/Debian/Fedora/CentOS, which will be introduced here. Still, install Python 3 and pip first.
1. Ubuntu/Debian：
- sudo apt update
- sudo apt install python3 python3-pip
2. Fedora：
- sudo dnf install python3 python3-pip
3. CentOS (use dnf for newer versions, yum for older versions):
- sudo yum install python3 python3-pip
And the following operations are totally the same as before, with installing by pip3 install -U yt-dlp and checking by yt-dlp --version.
There is another method that suits all kinds of Linux as well, which requires you to directly download the executable file.
- If installed with Homebrew, use brew upgrade yt-dlp
- If installed with pip, use python3 -m pip install -U yt-dlp or pip install -U yt-dlp
- If it is a directly downloaded executable file (yt-dlp or yt-dlp_linux, etc.), use yt-dlp -U
*If you get a permission denied error, just add sudo before the command, for example: sudo yt-dlp -U
Casual Commends for Quality/Bulk/Subtitle Options
Great! You've just arrived at yt-dlp's home. Now, let's settle in and explore how to turn yt-dlp into a reliable companion for downloading YouTube videos exactly the way you want. Here are some of the most commonly used yt-dlp commands to help you quickly select video quality, batch download, and handle subtitles.
All the commands should be typed in the CMD window. You know the way to open it, right? If you don't, go back to the last section and read the guide again.
Basic download
- Download a single video (replace the URL with the one you want to download): yt-dlp https://www.youtube.com/watch?v=XXXXXXXXXXX
- The downloaded video will be saved in the folder where your current terminal or the yt-dlp.exe is located. To check the location of yt-dlp, just input where yt-dlp is in CMD, and you will get it.
- Or you can just download the video to the ideal path by yt-dlp -P /your/custom/path https://www.youtube.com/watch?v=XXXXXXXXXXX
Bulk download
- Download a playlist:
To download all the videos in the entire playlist, use: yt-dlp https://www.youtube.com/playlist?list=XXXXXXXXXXX
- Batch download multiple videos
If the videos you want to download are from different playlists, you can create a new text file (for example, called urls.txt) and put one video URL on each line. Then enter the terminal: yt-dlp -a urls.txt. This will batch download all the URLs in the file.
Quality Options
The default download command will automatically select the highest quality.
- If you want to specify the resolution, such as 720p, use: yt-dlp -f "bestvideo[height<=720]+bestaudio/best[height<=720]" https://www.youtube.com/watch?v=XXXXXXXXXXX
- If you want to download only the audio as MP3, use: yt-dlp -x --audio-format mp3 https://www.youtube.com/watch?v=XXXXXXXXXXX
- If you want the video to be downloaded with certain codecs, such as MP4, use: yt-dlp https://www.youtube.com/watch?v=xxxxxxxx --recode-video mp4 --postprocessor-args "-c:v libx264"
Subtitle Options
- If you want to download a video with subtitles, just use yt-dlp --write-subs --sub-lang en https://www.youtube.com/watch?v=XXXXXXXXXXX
After --sub-lang, you can enter en (English), es (Spanish), fr (French), etc., depending on which language subtitles you want. If you don't know the specific language code that fits your idea, just Google "ISO 639-1 standard language codes".
- If you want the subtitles only (not the video): yt-dlp --skip-download --write-subs --sub-lang en https://www.youtube.com/watch?v=XXXXXXXXXXX
- There is a special command for the case that no manual subtitles exist, but only the auto-created by YouTube: yt-dlp --write-auto-subs --sub-lang en https://www.youtube.com/watch?v=XXXXXXXXXXX
Other commonly used commands
- Custom save file name: yt-dlp -o "%(title)s.%(ext)s" https://www.youtube.com/watch?v=XXXXXXXXXXX
- Limit download speed (for example, 1M per second): yt-dlp --limit-rate 1M https://www.youtube.com/watch?v=XXXXXXXXXXX
- Download only a segment of the video (for example, 1:00~2:00): yt-dlp --download-sections "*00:01:00-00:02:00" https://www.youtube.com/watch?v=XXXXXXXXXXX
How to Merge Video & Audio with FFmpeg?
When downloading some high-definition videos with yt-dlp, the video and audio may be saved separately (for example, you may get a .webm and a .m4a file). In this case, you need to use FFmpeg to merge them into a complete video file.
1. Install FFmpeg
After installation, remember to enter ffmpeg -version to check!
Windows
Enter brew install ffmpeg in the terminal. If you don't have Homebrew, install Homebrew first (https://brew.sh/), and then run the above command.
Linux
Ubuntu/Debian:
- sudo apt update
- sudo apt install ffmpeg
Fedora/CentOS:
- sudo dnf install ffmpeg
Arch:
- sudo pacman -S ffmpeg
2. Merge audio & video with the command
So you've got a couple of files, "video.webm” and "audio.m4a", sitting in a folder. Open CMD or Terminal (I always mix these up), use cd to get to the right folder, and then type: ffmpeg -i video.webm -i audio.m4a -c copy output.mp4. Done! It’s kind of satisfying, isn’t it?
What's that?
- -i video.webm: input video
- -i audio.m4a: input audio
- -c copy: directly copy streams without re-encoding, fast speed
- output.mp4: output file name
Remember to replace the file names with the actual names of the video and audio files you downloaded. The output file will be in the current folder.
3. Auto-merge with yt-dlp
As long as FFmpeg is installed, yt-dlp will automatically merge the video and audio, so you generally don't need to do it manually. Just use the basic download command. If you only have separate audio and video files, you need to merge them yourself and then use the command from step 2 above.
| Error Notice | Solution |
|---|---|
|
"ffmpeg is not recognized as an internal or external command" |
The environment variable is not set correctly. It is recommended to restart the command line or reset the Path. |
|
No sound/video after merging |
Check the file names and formats, and make sure both files are complete. |
|
yt-dlp merge failed |
Check whether FFmpeg is properly installed and configured in the system Path. |
Troubleshooting Issues on YT-DLP
| Issues | Common Reason | Solutions |
|---|---|---|
|
yt-dlp cannot download the video |
|
|
|
Error “ffmpeg not found” or merge failed |
|
|
|
Error “ERROR: Unable to extract ...” or “extractor error” |
|
|
|
The download speed is very slow |
|
|
|
Only audio/video downloaded |
|
|
|
Prompt “unsupported URL” or “Unsupported site” |
|
|
|
Error “Permission denied” or “Access denied” |
|
|
|
Video is encrypted, or a login is required |
|
|
|
yt-dlp is unresponsive or crashes |
|
|
You encountered a totally unknown issue while using yt-dlp? Ask the AIs or check if someone has already reported it on the GitHub issues page of yt-dlp.
- 🌟Achievement Unlocked: You now handle the handle of yt-dlp! Swing it to harvest the videos you want from the borderless internet!
Best GUI YT-DLP Alternatives in 2025
Has the excitement of learning to use yt-dlp worn off? Or do you think the invention of tools is meant to keep iterating and simplifying manual operations? Totally understand! Next, I'll recommend some yt-dlp branches with GUIs to you. I've used most of them or am still using them now. Additionally, for security, aesthetics, and convenience, I've also included some of the GOATs from r/youtube-dl and r/software.
1. Stacher7
Honestly, there are a gazillion yt-dlp wrappers with GUIs out there. Seriously, you can get dizzy just scrolling through them all. So why did I pick Stacher7? No grand reason, just that I kind of like how its interface looks. Since the common yt-dlp wrappers have 99% same functions, aesthetics matter a bit to me. Feature-wise, it's super practical: task queues, download progress bars, a handy history, and it even updates yt-dlp for you. Solid choice for most folks.
- Cross-platform support (Windows, macOS, Linux)
- Open source and free, no ads
- Supports a vast number of websites
- Simple and user-friendly interface, easy to use
- Features are not as rich as some commercial software
2. Seal
For mobile users, or, to be more precise, for Android users, Seal is a trustworthy option. I know someone may prefer NewPipe, but as far as I am concerned, a tool should be a tool only. I'm not judging NewPipe users, and that is only my personal idea. Use any yt-dlp with a GUI as you like anyway.
Back to Seal itself, I especially like its appearance. Its underlying integration includes tools such as yt-dlp, aria2, and FFmpeg. In addition to supporting batch tasks and multi-threaded downloads, Seal also integrates relatively rich customization options, such as automatic file naming, watermark removal, subtitle extraction, and other features. It is completely free and ad-free, and supports multiple languages. Just a couple of days ago, I used it to download a song from YouTube.
- Free and ad-free
- Supports numerous websites
- Supports batch tasks and multi-threading
- Beautiful and modern interface. I like it
- Not available on Google Play, but only on GitHub
- Advanced features require a certain level of technical expertise
- Compatibility depends on the update frequency of yt-dlp
3. Documents by Readdle
Now it's iOS usable recommendation time. However, because the OS is closed, there are no official or mainstream yt-dlp GUI tools. I put an alternative here for iOS users to download videos: Documents by Readdle.
You know, I always say “A tool is just a tool,” and while I still stand by that, I have to admit that given the software out there, this one’s not half bad. What’s cool is, you can download files directly (pictures, songs, videos, you name it) right from web pages using its browser. Oh, and it plays nicely with other Readdle apps, like PDF Expert. Handy, right?
- User-friendly interface and smooth operation, easy to use
- Integrated local and cloud file management, supports multiple cloud services
- Built-in browser allows direct download of web files
- Supports various tools such as document preview, media playback, and decompression
- Some advanced features require a subscription or in-app purchase to unlock
- Downloading certain resources is restricted by iOS system permissions, and not all types of resources can be downloaded
- Some third-party cloud service interfaces may occasionally be unstable
4. StreamFab YouTube Downloader Pro
If you want my genuine opinion (which, well, you’re getting anyhow), this tool is actually pretty nifty. The built-in browser allows me to poke around, searching, then pulling audio or video straight from websites, no jumping through hoops. Hardware acceleration makes downloads zip by.
Sure, things like 8K UHD, VR 360°, or downloading YouTube movies need the paid upgrade, and we always grumble about paywalls, but it’s still really solid for people who care about download speed and quality. I have to mention its auto-download, which keeps an eye on our subscribed YouTubers and just grabs their new stuff for us. Seriously convenient.
A fully-featured video download software designed for Windows and macOS users, with support for over 1000+ websites.
- Supports a wide range of video websites, highly compatible
- Multiple resolution options (up to 8K) and audio formats
- Supports batch downloads, playlists, and channel downloads
- Built-in browser for a smooth download experience
- Supports automatic extraction of subtitles and metadata
- Hardware acceleration for fast download speeds
- Some advanced features/high-quality downloads require payment to unlock.
Conclusion
Congrats, you made it! This guide covered the basics, from installation and updates to downloading, merging, working with subtitles, batches, plus those annoying troubleshooting bits. Now, the next step is pretty simple: get in there and try things out. Seriously, just poke around with yt-dlp --help and mess with the options for your own needs, like playlists, course videos, or keeping backups. With some hands-on practice, you'll soon find yt-dlp becoming your trusty go-to for grabbing videos, quickly, reliably, wherever you happen to be.
