How to Use yt-dlp: The Beginner's Guide (First Download, Format Picks, Audio, Playlists, and the Legal-Use Line)
CodexFuse Team · 2026-10-30T10:51:07.416Z · 10 min read
If you are learning how to use yt-dlp, you are starting at the right place. yt-dlp is the command-line tool that beginners reach for when they want to save a video for offline viewing, pull the audio out of a lecture, or archive an entire playlist — and this guide walks you from installation to your first download, format picks, MP3 audio, playlists, and subtitles in copy-paste steps. No terminal experience is assumed. (And if you would rather skip the command line entirely, CodexFuse has a video downloader that handles video links right in the browser.)
What is yt-dlp?
yt-dlp is a free, open-source, command-line audio/video downloader with support for thousands of websites. It is the actively maintained successor to youtube-dl — the project is a fork based on the now-inactive youtube-dlc, it holds more than 200,000 stars on GitHub, and it is released under the Unlicense.
Why do beginners pick it over the hundreds of online downloaders? Three reasons: it is scriptable, so you can automate recurring downloads; it exposes quality choices that browser extensions hide; and it is honest about what it is doing — one command, one file, no ads or bundled software.
How is yt-dlp different from youtube-dl?
youtube-dl was the original tool and still works for some sites, but its development slowed down years ago while video platforms kept changing. yt-dlp forked it, added hundreds of site extractors, and — crucially — adopted smarter format sorting and merging so modern separate-stream video (which is how YouTube now serves anything above 720p) downloads and merges cleanly. For a beginner in 2026, there is no contest: install yt-dlp, not youtube-dl.
How do you install yt-dlp on Windows, Mac, and Linux?
Install the official release binary for your operating system from the project's GitHub releases page — that is the route the project itself recommends, and it is what the install evidence below follows.
Install on Windows
Download yt-dlp.exe (the Windows Win10+ standalone x64 binary, recommended for Windows) from the GitHub releases page and put it in a folder of your choice, for example C:\tools. Open a terminal in that folder — you can type cmd in the File Explorer address bar — and run yt-dlp --version; if a date appears, you are set.
Install on Mac
Download yt-dlp_macos (the universal macOS 10.15+ standalone executable, recommended for macOS) from the GitHub releases page, move it somewhere on your PATH such as /usr/local/bin/yt-dlp, and make it executable with chmod +x. If you use Homebrew, brew install yt-dlp works too. Then verify with yt-dlp --version.
Install on Linux
Download yt-dlp_linux (the standalone x86_64 binary for glibc 2.17+) or the platform-independent yt-dlp zipimport binary — the README recommends the latter for Linux/BSD, and it needs Python on the system. Alternatively install with pip: python3 -m pip install -U yt-dlp. Move the binary to /usr/local/bin, make it executable, and verify with yt-dlp --version.
Install FFmpeg too (non-negotiable)
FFmpeg is the dependency the yt-dlp README marks as strongly recommended, because it is required for merging separate video and audio files and for audio conversion. Without it, downloads from YouTube are stuck at 720p or lower: modern YouTube serves high resolutions as separate video and audio streams, and only FFmpeg can stitch them back together. Install it per OS — brew install ffmpeg on macOS, sudo apt install ffmpeg on Debian/Ubuntu, or a Windows build from ffmpeg.org added to your PATH. Our FFmpeg beginner guide covers the install in detail if you get stuck.
How do you use yt-dlp for the first time?
Your first download takes four steps and about two minutes once the tools above are installed. Use a video you own or have permission to save — your own upload, a Creative Commons lecture, anything licensed for it.
- Copy the video's URL from your browser.
- Open your terminal and navigate to the folder where you want the file (downloads land in the current directory).
- Paste the URL inside quotes and run it:
yt-dlp "https://www.youtube.com/watch?v=VIDEO_ID"— the quotes matter because video URLs contain&and?, which the shell would otherwise interpret. - Watch the progress bar. When it finishes, you have the best available quality in your folder.
That is the whole model: options first, URL last. Every command in this guide follows the shape yt-dlp [OPTIONS] URL.
How do you pick the format and quality?
By default yt-dlp grabs the best available quality, which can mean a multi-gigabyte file for a long 4K video. Two commands put you in control: one lists what exists, the other selects it.
Run yt-dlp -F "URL". It downloads nothing — it prints a table of format codes with resolution, codec, and bitrate for each stream. Once you see the table, you pick by code and combine video and audio with a plus sign, for example yt-dlp -f 137+140 "URL".
Most beginners skip the code table and just cap the resolution. The table below is the one asset to bookmark — each row is one command.
| Goal | Command |
|---|---|
| Cap at 720p (smallest good file) | yt-dlp -f "best[height<=720]" "URL" |
| Cap at 1080p with H.264/AAC (plays everywhere, no transcoding) | yt-dlp -S "res:1080,vcodec:h264,acodec:aac" "URL" |
| Maximum quality, merge to MP4 | yt-dlp --merge-output-format mp4 "URL" |
| Best audio only, keep original format | yt-dlp -f bestaudio "URL" |
| Tidy filenames with the video title | yt-dlp -o "%(title)s.%(ext)s" "URL" |
The -S sort flag is the beginner's friend: instead of memorizing format codes, you describe what you want and yt-dlp picks the best match.
How do you download audio as MP3 with yt-dlp?
Add -x (extract audio) plus the format: yt-dlp -x --audio-format mp3 "URL". FFmpeg converts the audio behind the scenes and the video file is discarded, so you need FFmpeg installed for this to work. For the highest MP3 quality, append --audio-quality 0.
This is the yt-dlp MP3 workflow podcast listeners and students use: one command turns a lecture video into a file that plays on any phone. Note that --audio-format m4a converts faster and keeps quality closer to the original — MP3 is only the right pick when you need maximum device compatibility.
How do you download a whole playlist with yt-dlp?
Paste the playlist URL and yt-dlp walks through every video automatically — playlists are first-class citizens, not a hack. To grab only part of a playlist, add --playlist-items 5-10 for videos five through ten. Number the files in playlist order with an output template: yt-dlp -o "%(playlist_index)03d - %(title)s.%(ext)s" "PLAYLIST_URL".
Two honest boundaries: playlists on private or member-only channels need authentication, which is a deeper topic than this beginner guide; and if your other lane is file sharing rather than direct media, our qBittorrent beginner guide covers the torrent side of downloading. Keep playlist downloads to content you own or that is openly licensed.
How do you download subtitles with yt-dlp?
Check what subtitle tracks exist first with yt-dlp --list-subs "URL", then download them: yt-dlp --write-subs --sub-langs "en.*" "URL". YouTube serves subtitles as VTT; most media servers and older players expect SRT, so convert during the download with --convert-subs srt, and bake them into the file with --embed-subs to avoid sidecar files: yt-dlp --write-subs --sub-langs "en.*" --convert-subs srt --embed-subs --merge-output-format mp4 "URL".
What content is legal to download with yt-dlp?
yt-dlp does not judge legality — the video's license and the site's terms do. The safe line for beginners: your own uploads, public-domain works, and Creative Commons-licensed content. Many creators also permit offline viewing of their videos, and paid services like YouTube Premium cover offline access inside their apps instead. Never build an archive of someone else's paid or restricted content with yt-dlp; that is the use that gets accounts struck and tools blocked.
How do you keep yt-dlp updated?
YouTube changes its delivery code constantly and breaks older yt-dlp builds, so updating is a habit, not an afterthought. If you installed a release binary, run yt-dlp -U; if you installed with pip, re-run the same install command. The project even warns you: any version older than 90 days prints a reminder to update.
When a download suddenly fails with a 403 Forbidden error and your command is fine, an update is the first fix to try — most "yt-dlp stopped working" reports are YouTube's bot defenses against an old build, not a bug in your flags. If the stable release still breaks, the README recommends the nightly channel (yt-dlp --update-to nightly), which ships fixes within a day of a site change.
How to use yt-dlp — the cheat sheet
Every task above, compressed into one reference:
| Task | Command |
|---|---|
| Install check | yt-dlp --version |
| First download | yt-dlp "URL" |
| List formats | yt-dlp -F "URL" |
| 720p cap | yt-dlp -f "best[height<=720]" "URL" |
| Audio to MP3 | yt-dlp -x --audio-format mp3 "URL" |
| Whole playlist | yt-dlp "PLAYLIST_URL" |
| Playlist range | yt-dlp --playlist-items 5-10 "PLAYLIST_URL" |
| Subtitles to SRT | yt-dlp --write-subs --sub-langs "en.*" --convert-subs srt "URL" |
| Update | yt-dlp -U |
Save the files somewhere sensible, give them a watch with the VLC beginner guide if you want a player that opens anything, and keep the authorized-content line in mind every time you paste a URL.
Sources
- yt-dlp official GitHub repository — README: installation release files, update channels, and the ffmpeg/ffprobe dependency section (fetched 2026-10-30; repo reports 203,832 stars and thousands of supported sites)
- Vid Kraken — "How to Use yt-dlp: A Practical Guide (2026)" — URL-quoting rule, -F format list, -S sorting, MP3 extraction, -U update habit
- BlackMoreOps — "yt-dlp Commands for Subtitles, Codec and Folders" — codec sorting for media servers, --convert-subs srt, --embed-subs, output templates
- dev.to — "yt-dlp for youtube video downloads" — brew/pip install routes, 720p format selector, bestaudio, subtitle flags
- UbuntuShell — "Download YouTube Videos on Linux from CLI Using yt-dlp" — standalone binary install, --list-subs subtitle workflow
Frequently asked questions
Is yt-dlp safe to install?
Yes, when you download it from the official GitHub releases page. It is open-source, has hundreds of contributors and over 200,000 stars, and the binaries are signed with verifiable checksums. The risk comes from third-party sites repackaging it with bundled software.
Is it legal to download YouTube videos with yt-dlp?
It depends on the content, not the tool. Your own videos, public-domain works, and Creative Commons-licensed videos are fine; paid, restricted, or other creators' copyrighted work is not — and YouTube's terms of service forbid downloading regardless. Keep to the authorized-content line described above.
Why did yt-dlp stop working with a 403 error?
Almost always because the build is old: YouTube constantly changes its bot defenses. Run yt-dlp -U first, and if the stable release still fails, switch to the nightly channel with yt-dlp --update-to nightly, which the project recommends as its fix-fast channel.
Does yt-dlp work without FFmpeg?
Partially. It downloads fine, but anything above 720p arrives as separate video and audio streams that only FFmpeg can merge, and MP3 extraction needs it too. Install FFmpeg alongside yt-dlp — the project's README lists it as strongly recommended.
What is the difference between yt-dlp and youtube-dl?
yt-dlp is the actively maintained fork of youtube-dl, built on the inactive youtube-dlc. It adds far more site support, smarter format sorting, and reliable merging of modern separate-stream video, while youtube-dl's development has stalled.