Quick answer: Install yt-dlp and FFmpeg, open a terminal (Command Prompt, PowerShell, or Terminal), and run yt-dlp "VIDEO_URL". The video saves in the folder where you ran the command. For audio, add -x --audio-format mp3. To see all quality options, add -F. To update, run yt-dlp -U.
yt-dlp is a free, open-source command-line tool for downloading video and audio from YouTube and many other sites. It looks scary at first because there is no window or button, but you only need a handful of commands. This guide shows you how to use yt-dlp step by step, for beginners on Windows, Mac, and Linux.
Please read first: Only download content you have the right to download, such as your own videos, Creative Commons or public domain content, or content where the owner allows it. Downloading can break a site’s terms of service and copyright law in your country. This guide is for lawful use only.
What Is yt-dlp?
yt-dlp is a command-line program that downloads audio and video from YouTube and thousands of other sites. It is an actively maintained fork of the older youtube-dl, with more features and faster fixes. You will also see it written as “ytdlp” or “yt dlp,” but the official name is yt-dlp.
What it can do:
- Download video in different qualities and formats
- Extract audio as MP3, M4A, and more
- Download whole playlists
- Save subtitles, thumbnails, and metadata
- Download only a part of a video
yt-dlp vs youtube-dl
youtube-dl is the older project. yt-dlp started as a fork and is now the one most people use, because it gets updates and site fixes much more often. If you have an old youtube-dl tutorial, most commands work in yt-dlp with the name changed. On a Mac, use yt-dlp instead of youtube-dl.
Is yt-dlp Safe?
The official tool is open source, so anyone can read its code. It is generally considered safe if you download it from the right place:
- Get it only from the official GitHub page (github.com/yt-dlp/yt-dlp) or a trusted package manager (winget, Homebrew, pip)
- Avoid random websites, “yt-dlp installers,” and cracked downloaders. Fake copies are a common way to spread malware
- Be careful with browser extensions and unofficial apps that claim to be yt-dlp. Check who made them first
- Never run a command you do not understand
What You Need Before You Start
- yt-dlp itself
- FFmpeg (needed to merge video and audio, and to convert to MP3)
- A JavaScript runtime (needed for full YouTube support, Deno is recommended)
Recent yt-dlp versions strongly encourage YouTube users to install a JavaScript runtime such as Deno, because format availability can be limited without one. The official yt-dlp executables already include the component that works with it, so you mostly just need the runtime.
How to Install yt-dlp
Windows
Option A (easiest, winget): open Command Prompt or PowerShell and run:
winget install yt-dlp.yt-dlp
winget install Gyan.FFmpeg
winget install DenoLand.DenoOption B (manual):
- Go to the official yt-dlp GitHub releases page.
- Download yt-dlp.exe.
- Put it in a folder, for example
C:\yt-dlp. - Add that folder to your PATH, or open the terminal inside that folder and run
yt-dlp.exe.
Close and reopen your terminal after installing.
Mac
Install Homebrew first if you do not have it, then run:
brew install yt-dlp ffmpeg denoLinux
Distro packages can be out of date, so the official binary is often best:
sudo curl -L https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp -o /usr/local/bin/yt-dlp
sudo chmod a+rx /usr/local/bin/yt-dlpThen install FFmpeg (for example sudo apt install ffmpeg) and a JavaScript runtime like Deno.
Any system with Python (pip)
python3 -m pip install -U "yt-dlp[default]"The [default] part installs the extra components yt-dlp needs for YouTube. You still need FFmpeg and a JavaScript runtime.
Check that it works
Run:
yt-dlp --versionIf you see a version number (a date like 2026.xx.xx), you are ready.
How to Install FFmpeg for yt-dlp
yt-dlp downloads video and audio as separate streams for high quality, and FFmpeg joins them into one file. It also converts audio to MP3. Without FFmpeg you may get videos with no sound, or errors about merging.
- Windows:
winget install Gyan.FFmpeg, or download a build from ffmpeg.org - Mac:
brew install ffmpeg - Linux:
sudo apt install ffmpeg(or your distro’s package manager)
Check with ffmpeg -version.
Your First Download (Command Line Basics)
- Open a terminal. On Windows, search for “Command Prompt” or “PowerShell.” On Mac, open “Terminal.”
- Go to the folder where you want the file, for example:
cd Downloads
- Copy the video URL from your browser.
- Run the command with the URL in quotes:
yt-dlp "https://www.youtube.com/watch?v=VIDEO_ID"
- Wait for the progress bar to finish.
By default, yt-dlp picks the best available video and audio and merges them.
Where Does yt-dlp Download To?
By default, files save in the folder where you ran the command (your current working directory). To choose another folder, use -P:
yt-dlp -P "C:\Users\YourName\Videos" "URL"Tip: Always put the URL in quotes, especially on Mac and Linux, because characters like & can break the command.
Most Useful yt-dlp Commands (Cheat Sheet)
| What you want | Command |
|---|---|
| Download a video | yt-dlp "URL" |
| List all formats and qualities | yt-dlp -F "URL" |
| Download a specific format | yt-dlp -f FORMAT_ID "URL" |
| Best quality up to 1080p | yt-dlp -f "bv*[height<=1080]+ba/b[height<=1080]" "URL" |
| Save as MP4 | yt-dlp --merge-output-format mp4 "URL" |
| Download audio as MP3 | yt-dlp -x --audio-format mp3 "URL" |
| Audio only, no conversion | yt-dlp -f ba "URL" |
| Download a playlist | yt-dlp "PLAYLIST_URL" |
| Download only one video from a playlist link | yt-dlp --no-playlist "URL" |
| First 5 videos of a playlist | yt-dlp --playlist-items 1-5 "PLAYLIST_URL" |
| Choose file name | yt-dlp -o "%(title)s.%(ext)s" "URL" |
| Choose folder | yt-dlp -P "FOLDER_PATH" "URL" |
| Download subtitles | yt-dlp --write-subs --sub-langs en "URL" |
| Save thumbnail only | yt-dlp --write-thumbnail --skip-download "URL" |
| Download a batch of links | yt-dlp -a urls.txt |
| Update yt-dlp | yt-dlp -U |
How to Choose Video Quality
Step 1: See the available formats
yt-dlp -F "URL"You will see a table with format IDs, resolution, file type, and size.
Step 2: Pick a format
- To download a specific video and audio pair, join their IDs with a plus sign:
yt-dlp -f 137+140 "URL"
(Format IDs change from video to video, so read your own table.)
- To get the best quality up to 1080p without checking IDs:
yt-dlp -f "bv*[height<=1080]+ba/b[height<=1080]" "URL"
- Change
1080to720or480for smaller files.
A shorter option is yt-dlp -S "res:720" "URL", which prefers the best quality up to 720p.
How to Download MP4 With yt-dlp
Some videos merge into .webm or .mkv by default. To get an MP4:
yt-dlp --merge-output-format mp4 "URL"If you need a file that plays on almost any device, this also helps:
yt-dlp -S "vcodec:h264,res,acodec:m4a" --merge-output-format mp4 "URL"How to Download Audio and MP3 With yt-dlp
Convert to MP3
yt-dlp -x --audio-format mp3 "URL"-xmeans extract audio--audio-format mp3converts it to MP3- Add
--audio-quality 0for the best quality
This step needs FFmpeg.
Audio Only Without Converting
yt-dlp -f ba "URL"This saves the best audio in its original format, often WebM (Opus) or M4A. There is no conversion, so quality stays the same.
yt-dlp audio: WebM or MP3? WebM/Opus and M4A usually give better quality for the file size. MP3 works on the most players and devices. Choose MP3 for compatibility, and the original format for quality.
Smaller Audio Files (Worst Audio)
yt-dlp -f wa "URL"wa means worst audio. It gives the lowest-quality audio, which is usually a smaller file. Use it only when file size matters more than sound quality. To keep it small and convert it, combine it with -x.
How to Download a Playlist
yt-dlp "PLAYLIST_URL"Useful options:
- Only some videos:
--playlist-items 1-10 - Number the files and put them in a folder:
yt-dlp -o "%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s" "PLAYLIST_URL"
- Only the single video when the link contains a playlist:
--no-playlist - Skip videos you already have:
--download-archive archive.txt
Save Subtitles, Thumbnails, and Metadata
- Subtitles:
yt-dlp --write-subs --sub-langs en "URL" - Auto-generated subtitles:
yt-dlp --write-auto-subs --sub-langs en "URL" - Embed subtitles in the video: add
--embed-subs - Thumbnail only (thumbnail downloader):
yt-dlp --write-thumbnail --skip-download "URL" - Embed the thumbnail and tags in the file:
--embed-thumbnail --embed-metadata
Download Only Part of a Video
You can save just a section, for example from 1:00 to 2:30:
yt-dlp --download-sections "*1:00-2:30" "URL"This needs FFmpeg.
Download Many Links at Once
- Create a text file called
urls.txt. - Put one link per line.
- Run:
yt-dlp -a urls.txt
Age-Restricted or Members-Only Videos You Can Access
If a video needs you to be logged in (for example, an age-restricted video or one from a channel you are a member of), yt-dlp can use the cookies from your browser:
yt-dlp --cookies-from-browser chrome "URL"Replace chrome with firefox, edge, or your browser. Only use this for content your account is allowed to view, and keep your cookies private.
How to Update yt-dlp
Sites change often, so updating is the first fix for most problems. Use the method that matches how you installed it:
| How you installed it | Update command |
|---|---|
| Downloaded the official executable | yt-dlp -U |
| pip | python3 -m pip install -U "yt-dlp[default]" |
| Homebrew | brew upgrade yt-dlp |
| winget | winget upgrade yt-dlp.yt-dlp |
For the newest fixes, advanced users can switch to the nightly build with yt-dlp --update-to nightly.
Is There a yt-dlp GUI?
yt-dlp itself has no official graphical interface. Some third-party apps add buttons and menus on top of yt-dlp, for example Open Video Downloader, Tartube, and other “yt-dlp GUI” tools. Before using one:
- Download it only from its official GitHub or website
- Check that it is actively updated (old GUIs break when sites change)
- Remember that the GUI still needs yt-dlp and FFmpeg to work
yt-dlp Chrome Extension and Online Versions
There is no official yt-dlp Chrome extension or online website. Anything that claims to be one is made by someone else, and some are unsafe or spam. If you want a simple interface, choose a trusted desktop GUI instead.
Common yt-dlp Errors and Fixes
| Problem | Fix |
|---|---|
'yt-dlp' is not recognized | The tool is not in your PATH. Add its folder to PATH, or run the command from the folder containing yt-dlp.exe |
| Video has no sound, or merge error | Install FFmpeg and reopen the terminal |
ffmpeg not found | Install FFmpeg, or point to it with --ffmpeg-location "PATH" |
| Warning about a missing JavaScript runtime | Install Deno (or another supported runtime) and update yt-dlp |
| HTTP Error 403: Forbidden | Update yt-dlp, and install a JavaScript runtime |
| “Sign in to confirm you’re not a bot” | Update yt-dlp, and try --cookies-from-browser. Check the official wiki, because this changes often |
| Only low-quality formats appear | Update yt-dlp and install a JavaScript runtime |
| Command works in one terminal but not another | Check quotes around the URL. Use double quotes on Windows |
| Download is slow | Try --limit-rate off, a different network, or download at a lower quality |
When you ask for help, run the command with -vU (verbose and update) and share the output. The yt-dlp GitHub issues page asks for this.
Tips for Beginners
- Always update first if something stops working.
- Use quotes around every URL.
- Use
-Fto see the real format list before choosing a quality. - Start simple, then add options one at a time.
- Save your favorite options in a config file so you do not retype them. See the official README for where the file goes on your system.
- Keep the tool, FFmpeg, and your JavaScript runtime up to date.
Conclusion
Now you know how to use yt-dlp: install it with FFmpeg and a JavaScript runtime, paste a URL into the command line, use -F to pick quality, add -x --audio-format mp3 for audio, and run yt-dlp -U whenever something breaks. Start with one or two commands from the cheat sheet, and add more as you get comfortable. And always download only content you are allowed to save.
Disclaimer: This guide is for educational purposes. You are responsible for following copyright law, site terms of service, and local rules. Commands and requirements can change with updates, so check the official yt-dlp documentation for the latest details.
FAQs
1. How do I use yt-dlp?
Install yt-dlp and FFmpeg, open a terminal, and run yt-dlp "VIDEO_URL". The video saves in your current folder. Add options like -F (list formats) or -x --audio-format mp3 (audio) as needed.
2. How do I install yt-dlp?
On Windows, run winget install yt-dlp.yt-dlp. On Mac, run brew install yt-dlp. You can also download the official executable from GitHub or use python3 -m pip install -U "yt-dlp[default]".
3. Do I need FFmpeg for yt-dlp?
Yes, for most downloads. FFmpeg merges the separate video and audio streams and converts audio to MP3. Without it you may get silent video or errors.
4. How do I update yt-dlp?
Run yt-dlp -U if you use the official executable, pip install -U "yt-dlp[default]" if you installed with pip, brew upgrade yt-dlp on Homebrew, or winget upgrade yt-dlp.yt-dlp on winget.
5. How do I download MP3 with yt-dlp?
Run yt-dlp -x --audio-format mp3 "URL". This needs FFmpeg. Add --audio-quality 0 for the best quality.
6. How do I download only audio?
Run yt-dlp -f ba "URL" to save the best audio in its original format, often WebM or M4A, without converting it.
7. How do I download in MP4?
Run yt-dlp --merge-output-format mp4 "URL". For wide device compatibility, add -S "vcodec:h264,res,acodec:m4a".
8. Where does yt-dlp save files?
In the folder where you ran the command. Use -P "FOLDER" to choose a different folder.
9. Is yt-dlp safe?
The official open-source tool is generally safe when downloaded from its official GitHub page or a trusted package manager. Avoid unofficial installers, fake websites, and unknown extensions.
10. Is there a yt-dlp GUI or Chrome extension?
yt-dlp has no official GUI or browser extension. Some third-party GUIs exist, but download them only from their official pages and make sure they are still updated.
11. Why does yt-dlp say a JavaScript runtime is missing?
Recent versions need a runtime such as Deno for full YouTube support. Install Deno (for example winget install DenoLand.Deno or brew install deno) and update yt-dlp.
12. How do I download a playlist with yt-dlp?
Run yt-dlp "PLAYLIST_URL". Use --playlist-items 1-10 for only some videos, and --no-playlist if you want just the single video from a link that also contains a playlist.
13. Is it legal to use yt-dlp?
The tool itself is legal software, but what you download matters. Downloading copyrighted content without permission, or against a site’s terms, can be illegal or break the rules. Only save content you have the right to download.
