If you opened this yt-dlp guide because the terminal, installation path, or output format feels unclear, start with one authorized download. The yt-dlp command line becomes manageable once you verify the setup, find the saved file, then add MP4 selection, playlists, subtitles, troubleshooting, or a GUI.
You can download YouTube videos with a repeatable setup. Follow the installation path for your computer, confirm a saved file, then add the options you need.
- How to install and update yt-dlp?
- How to use yt-dlp in your ideal way?
- How to merge video & audio downloaded separately via yt-dlp?
- Troubleshooting common issues while using yt-dlp
- Best GUI yt-dlp alternatives for newbies
This yt-dlp guide connects installation, updates, yt-dlp commands, MP4 selection, and FFmpeg merging. Start with a quoted video URL, then add quality and folder options.
Install and Update yt-dlp on Windows, macOS, and Linux
YouTube extraction in yt-dlp uses an external JavaScript runtime and EJS components. Deno is the recommended runtime, and the pip default dependency group includes the EJS package. FFmpeg and ffprobe handle merging and post-processing. As of September 2026, the latest stable release is 2026.08.19. Use yt-dlp --version to identify your installed copy.
1. Install yt-dlp on Windows
Windows 10 and Windows 11 use the same pip installation path below. Open Command Prompt or PowerShell after installation. The default dependency group includes EJS; Deno is the recommended external JavaScript runtime. Install Deno separately and run deno --version to confirm it is available.
2. Install yt-dlp on macOS
Homebrew keeps yt-dlp on Mac and its supporting tools in one update channel. I would use this route for a first installation. Open Terminal, install the dependencies, and confirm that each command responds before starting a download.
Use these commands only for content you are authorized to access and save for personal offline viewing, where platform terms and applicable law permit it. Do not redistribute downloaded content.
A Python environment is another installation route on macOS. Run python3 -m pip install -U "yt-dlp[default]" in that environment, then check yt-dlp --version. For package-manager installations, confirm that the package supplies EJS and that deno --version succeeds; a working yt-dlp command alone does not confirm the runtime setup.
3. Install yt-dlp on Linux
Install yt-dlp on Linux using a package manager, an isolated Python environment, or the standalone executable. Start with Python 3 and pip for the Python route. Your distribution determines which package command to use.
Ubuntu/Debian: Refresh package information before installing Python.
- Run sudo apt update.
- Run sudo apt install python3 python3-pip.
Fedora: Install Python and pip with dnf.
- Run sudo dnf install python3 python3-pip.
CentOS: Use dnf on newer releases or yum on older releases.
- For the yum route, run sudo yum install python3 python3-pip.
Install or update inside your Python environment with python3 -m pip install -U "yt-dlp[default]". The dependency group includes EJS. Add Deno and verify it with deno --version; use your distribution's FFmpeg package for merging. If system-wide pip installation is blocked, use a virtual environment or pipx instead of forcing a system installation.
- Homebrew: brew upgrade yt-dlp.
- pip: python -m pip install -U "yt-dlp[default]", or python3 -m pip install -U "yt-dlp[default]" in your Python environment.
- Supported self-updating release binaries: run yt-dlp -U. For a package-manager installation, use that package manager instead.
If a permission error appears, use the account and environment that installed the tool; avoid elevating privileges before identifying the installation location.
Use yt-dlp Commands for Quality, Playlists, Subtitles, and Filenames
Run yt-dlp commands in Command Prompt or PowerShell on Windows, or Terminal on macOS. Save a local copy only for personal offline viewing of content you are authorized to access and save. Do not redistribute it, and follow applicable law and the platform’s terms; permission depends on the content and your intended use.
Download one video and choose the folder
- Download one video: yt-dlp "VIDEO_URL". Replace VIDEO_URL with an authorized video URL; wait for downloading and post-processing to finish.
- Locate the command with where yt-dlp in Command Prompt or where.exe yt-dlp in PowerShell. The result shows the executable path.
- Set the yt-dlp output folder: yt-dlp -P "/your/custom/path" "VIDEO_URL". Replace the path with your destination folder.
- Set a filename: yt-dlp -o "%(title)s.%(ext)s" "VIDEO_URL". The final extension follows the selected format and completed post-processing.
Download playlists and batch URL files
- Download yt-dlp playlists with yt-dlp "PLAYLIST_URL". Replace PLAYLIST_URL with the playlist you are authorized to save.
- For a batch of URLs, create urls.txt with one URL per line, then run yt-dlp -a "urls.txt".
- Download HLS/DASH fragments concurrently: yt-dlp -N 4 "VIDEO_URL". This setting controls fragments within a download, not four separate video downloads.
Select quality, audio, and output format
Inspect available formats before choosing a yt-dlp MP4 command. Run yt-dlp -F "VIDEO_URL"; the list shows format IDs, containers, and codecs. MP4 is a container, not a guarantee of H.264 video or playback support on your device.
| Goal | Option | Dependency | Trade-off |
|---|---|---|---|
| Inspect source formats | -F | None | Lists available choices |
| Extract MP3 audio | -x --audio-format MP3 | FFmpeg | Audio-only output |
| Merge into MP4 | --merge-output-format MP4 | Separate streams, FFmpeg | Ignored without a merge |
| Remux to MP4 | --remux-video MP4 | Compatible codecs | No re-encoding |
| Recode to MP4 | --recode-video MP4 | FFmpeg | More time, quality trade-off |
- Limit video height to 720p: yt-dlp -f "bestvideo[height<=720]+bestaudio/best[height<=720]" "VIDEO_URL".
- Extract audio as MP3 with FFmpeg: yt-dlp -x --audio-format mp3 "VIDEO_URL".
- Convert to MP4 when required: yt-dlp --recode-video mp4 "VIDEO_URL". This is not a universal codec repair for an existing MP4.
- Select MP4-compatible source containers: yt-dlp -f "bv[ext=mp4]+ba[ext=m4a]/b[ext=mp4]" --merge-output-format mp4 "VIDEO_URL". The selector fails when no matching formats are available; it does not guarantee H.264.
--merge-output-format MP4 selects the container when yt-dlp merges separate streams and is ignored when no merge is needed. Keep the option value lowercase: MP4. Remuxing changes the container without re-encoding; MP4 alone does not specify the video codec. Remux compatible streams with yt-dlp --remux-video MP4 "VIDEO_URL" when the codecs fit the MP4 container. I prefer that route when the codecs already suit the player. Recoding requires additional processing and introduces a quality trade-off; use conversion when the codec needs to change. A different filename does not change the codec.
Download subtitles and video segments
- Save yt-dlp subtitles in English: yt-dlp --write-subs --sub-lang en "VIDEO_URL".
- Request automatic captions when manual subtitles are unavailable: yt-dlp --write-auto-subs --sub-lang en "VIDEO_URL".
- Download subtitles without video: yt-dlp --skip-download --write-subs --sub-lang en "VIDEO_URL".
- Save a segment from 1:00 to 2:00 with FFmpeg: yt-dlp --download-sections "*00:01:00-00:02:00" "VIDEO_URL".
The official supported-sites list includes many extractors, but it also warns that websites change and not every listed site will work at a given moment. If a URL fails, update yt-dlp first, test another URL from the same site, and check the project’s GitHub Issues before assuming your command is wrong.
Merge Video and Audio with FFmpeg Without Re-encoding
FFmpeg merges the separate video and audio streams that yt-dlp downloads. It also handles container changes and conversion. Keep both FFmpeg and ffprobe available in PATH, the list of folders your terminal searches for commands.
1. Install FFmpeg
After installation, run ffmpeg -version to check whether FFmpeg is available from your terminal.
Windows
macOS
Install with Homebrew: brew install ffmpeg. To update later, run brew upgrade ffmpeg.
Linux
Ubuntu/Debian: Refresh the package list before installing FFmpeg.
- Run sudo apt update.
- Run sudo apt install ffmpeg.
Fedora/CentOS: Use a configured repository that supplies FFmpeg.
- Run sudo dnf install ffmpeg.
Arch: Install FFmpeg through pacman.
- Run sudo pacman -S ffmpeg.
2. Merge audio and video manually
Merge existing files with ffmpeg -i "video.webm" -i "audio.m4a" -c copy "output.MP4" when their codecs fit the MP4 container. Open the terminal in their folder first. Stream copying leaves the codecs unchanged; renaming an incompatible stream cannot repair it.
What the command means: The two inputs are copied into one output container.
- -i "video.webm" identifies the video input.
- -i "audio.m4a" identifies the audio input.
- -c copy copies the streams without re-encoding.
- "output.mp4" names the output file; its streams must fit MP4.
Stream copying preserves the existing encoded media; conversion changes it. That distinction between direct download and re-encoding matters when a player rejects a codec. Use a compatible container for copying, or convert to codecs your player accepts. --recode-video MP4 alone does not force a codec change when the file is already MP4.
3. Let yt-dlp auto-merge with FFmpeg
FFmpeg automatically joins separate streams when yt-dlp selects both. The MP4 selection command is yt-dlp -f "bv[ext=MP4]+ba[ext=m4a]/b[ext=MP4]" --merge-output-format MP4 "VIDEO_URL". Keep the option value lowercase: MP4. The merge option is ignored when no merge is needed, and compatible streams remain unchanged rather than being re-encoded.
Fix Common yt-dlp Errors Before Replacing the Tool
Match the error to the stage that failed: launching the command, extracting a source, downloading streams, or merging files. Reinstalling everything is rarely a useful first diagnosis. Start with the relevant check below.
Installation and post-processing failures have distinct checks:
Source, access, and network errors require different fixes:
| Source problem | Check | Next action |
|---|---|---|
| Extractor error | Version, Deno, EJS | Update installation channel; verify runtime and distribution EJS package |
| Login-required or private video | Account access to the page | Use authorized account cookies privately; never share session files |
| Slow download | Network load and fragment requests | Pause other downloads; try -N 4; reduce failing concurrency |
| Unsupported URL | Supported-sites list; another URL from the site | Update yt-dlp; use a supported source or permitted download route |
If an error remains after updating, the most useful next step is to search the official yt-dlp GitHub Issues page with the exact error message and website name. This usually shows whether the issue is new, already fixed in a recent release, or waiting for extractor support.
Compare yt-dlp GUI Workflows by Device
A graphical user interface (GUI) replaces typed commands with visual controls. To compare yt-dlp GUI alternatives for playlists and quality, start with the device and workflow rather than treating these different categories as performance competitors. Use every workflow only for content you are authorized to access and save for personal offline viewing, where platform terms and applicable law permit it, and do not redistribute downloaded content. For permitted tasks such as downloading YouTube movies, choose a desktop queue, an Android client, or an iPhone and iPad file manager according to where you need to manage the file.
| Product | Device | Category | Typical task |
|---|---|---|---|
| NewPipe | Android | YouTube client | On-device viewing and saving |
| Documents by Readdle | iPhone / iPad | File manager | Organizing permitted downloads |
| StreamFab YouTube Downloader Pro | Windows / macOS | Desktop downloader | Managing playlists and quality visually |
I would keep yt-dlp for precise format and filename control. For a visual desktop queue, StreamFab offers playlist and quality selection; Documents by Readdle serves a different need, organizing files on an iPhone or iPad. On Linux, the native yt-dlp path above remains the direct command-line route, while StreamFab for Linux setup follows a separate workflow.
1. Stacher7
A Stacher7 alternative starts with a workflow choice: keep yt-dlp commands for direct control, or use a desktop interface for visual tasks. A wrapper changes how you enter settings; the underlying downloader and FFmpeg still handle extraction and merging.
- Desktop interface for visual tasks.
- Extraction and merging still rely on underlying tools.
2. Seal
Seal is an Android interface based on yt-dlp. An interface and the downloader beneath it are separate parts of the workflow; changing the interface does not resolve a source-side extraction failure.
NewPipe is a separate Android option for YouTube viewing and saving. Choose an Android workflow for on-device use; keep desktop commands when you need to control the exact format selector and output filename.
- Android interface based on yt-dlp.
- Extraction relies on the integrated downloader.
3. Documents by Readdle
Documents by Readdle is an iPhone and iPad file manager, not a yt-dlp wrapper. It suits organizing downloads from pages that provide a permitted file download. It does not run the desktop commands shown above.
Its built-in browser saves supported web downloads into a file-management workflow. Keep the destination folder in view so you can find the file afterward. Source permissions still determine what is available to save.
- File management on iPhone and iPad.
- Built-in browser for supported web downloads.
- Not a yt-dlp interface.
4. StreamFab YouTube Downloader Pro
StreamFab YouTube Downloader Pro is a paid Windows and macOS desktop option for people who prefer visual playlist queues and quality selection over repeating command-line options. Use it only to save local copies of content you are authorized to access for personal offline viewing, where platform terms and applicable law permit it. It is not a route to unrestricted or permanent access. Attempts to interfere with content protections may be unlawful; do not use it that way or redistribute downloaded content.
The detailed StreamFab YouTube Downloader review explains how its visual queue handles playlist selection, quality choices, and output settings. That workflow is most useful when you repeat the same selections across multiple items; a single download may be quicker with one yt-dlp command. Supported sites and quality options can change, so update the app and use the official troubleshooting guide if a previously compatible source stops loading.
Advanced features require a paid plan; the StreamFab refund policy explains the applicable purchase terms.
A video downloader for Windows and macOS, with playlist downloads, metadata preservation, and output resolutions up to 8K for supported sources.
- Visual playlist and batch controls for repeated tasks.
- Source-dependent quality choices without writing format selectors.
- Advanced features require a paid plan.
FAQ About yt-dlp Commands, GUIs, and Troubleshooting
{{FAQ}}
Update Log
As of September 23, 2026, the latest stable yt-dlp release was 2026.08.19. Installed copies report their version through yt-dlp --version.
Choose yt-dlp for Control or a GUI for Convenience
Choose yt-dlp when you want direct control over formats, subtitles, filenames, and playlists. Keep its installation channel, FFmpeg, and JavaScript runtime in working order. One successful download gives you a setup worth building on.
Choose a GUI when visual selection makes repeated downloads easier. StreamFab provides desktop playlist and quality controls; NewPipe serves Android, while Documents by Readdle organizes permitted downloads on iPhone and iPad.
My recommendation is to start with one quoted URL and a known output folder. Add format selection after the file saves successfully. That sequence makes failures easier to locate and keeps a simple download simple.
