https://vulnerability.circl.lu Contains only the most 10 recent sightings. http://www.rssboard.org/rss-specification python-feedgen en Wed, 15 Jul 2026 19:24:52 +0000 https://vulnerability.circl.lu/sighting/3d2fd8e2-1d31-418a-9117-81b5a3a37f36/export {"uuid": "3d2fd8e2-1d31-418a-9117-81b5a3a37f36", "vulnerability_lookup_origin": "1a89b78e-f703-45f3-bb86-59eb712668bd", "author": "9f56dd64-161d-43a6-b9c3-555944290a09", "vulnerability": "CVE-2026-55404", "type": "seen", "source": "https://gist.github.com/akib-h/a603a4aaf4aab24ac683c30e9a2ad670", "content": "# The Ultimate yt-dlp Guide for Windows (10 & 11)\n\n> Researched against the official [yt-dlp GitHub repo](https://github.com/yt-dlp/yt-dlp), the [yt-dlp Wiki](https://github.com/yt-dlp/yt-dlp/wiki), and community sources, current as of **July 2026** (latest stable release: `2026.07.04`). yt-dlp updates constantly \u2014 always trust `yt-dlp --help` and `yt-dlp -U` over any guide, including this one.\n\n---\n\n## \ud83d\udccc TL;DR \u2014 Just Get It Working\n\nFor people who want the short version: this is the exact setup used throughout the rest of this guide (**MKV container, 1080p cap, best audio, with an easy way to grab the untouched original quality**).\n\n```powershell\n# 1. Install with winget (opens PowerShell as your normal user)\nwinget install yt-dlp.yt-dlp\nwinget install Gyan.FFmpeg\n\n# 2. Make a config folder + file\nmkdir \"$env:APPDATA\\yt-dlp\" -Force\nnotepad \"$env:APPDATA\\yt-dlp\\config.txt\"\n```\n\nPaste this into the config file, save, close:\n\n```ini\n# %APPDATA%\\yt-dlp\\config.txt\n# Prefer MKV, cap at 1080p, take the best audio available\n-S \"res:1080,vcodec:h264,acodec:aac\"\n--merge-output-format mkv\n--remux-video mkv\n-o \"%(uploader)s/%(title)s [%(id)s].%(ext)s\"\n-P \"~/Videos/yt-dlp\"\n--embed-thumbnail\n--embed-metadata\n--embed-chapters\n--download-archive \"%(home)s/yt-dlp-archive.txt\"\n--no-mtime\n```\n\nThen it's just:\n\n```powershell\n# Best up to 1080p, muxed into MKV automatically (uses the config above)\nyt-dlp \"https://www.youtube.com/watch?v=XXXXXXXXXXX\"\n\n# Grab the ORIGINAL/highest-available quality instead (ignores the 1080p cap for this run)\nyt-dlp -f \"bv*+ba/b\" -S \"res,vcodec:h264,acodec:aac\" --merge-output-format mkv \"URL\"\n\n# Audio only, best quality, as Opus\nyt-dlp -x --audio-format opus --audio-quality 0 \"URL\"\n```\n\nThat's the whole guide in three commands. Everything below explains *why* they work, what else exists, and how to fix it when it breaks. Jump to [\u00a722 Cheat Sheet](#22-frequently-used-commands-cheat-sheet) any time you just need a command.\n\n---\n\n## Table of Contents\n\n1. [Introduction](#1-introduction)\n2. [Installation](#2-installation)\n3. [FFmpeg](#3-ffmpeg)\n4. [Windows Terminal Basics](#4-windows-terminal-cmd-vs-powershell-vs-windows-terminal)\n5. [Basic Usage](#5-basic-usage)\n6. [Format Selection](#6-format-selection)\n7. [Configuration Files](#7-configuration-files)\n8. [Output Templates](#8-output-templates)\n9. [Authentication & Cookies](#9-authentication)\n10. [Batch Downloads](#10-batch-downloads)\n11. [Playlists](#11-playlists)\n12. [Audio Downloads](#12-audio-downloads)\n13. [Subtitles](#13-subtitle-downloads)\n14. [Metadata](#14-metadata)\n15. [SponsorBlock](#15-sponsorblock)\n16. [Advanced Features](#16-advanced-features)\n17. [Automation](#17-automation-windows-task-scheduler--scripts)\n18. [Performance Optimization](#18-performance-optimization)\n19. [Troubleshooting](#19-troubleshooting)\n20. [Windows-Specific Tips](#20-windows-specific-tips)\n21. [Best Practices](#21-best-practices)\n22. [Cheat Sheet](#22-frequently-used-commands-cheat-sheet)\n23. [Version Differences (youtube-dl vs yt-dlp)](#23-version-differences)\n24. [GUI Alternatives](#24-gui-alternatives)\n25. [Appendix](#25-appendix)\n\n---\n\n## 1. Introduction\n\n### What yt-dlp is\n\nyt-dlp is a free, open-source, command-line media downloader for Windows, macOS, Linux, BSD and Android. It's a fork of `youtube-dl` (via the intermediate `youtube-dlc` fork), maintained by an active community that ships releases roughly every one to two weeks. It's written in Python, distributed as both a standalone Windows `.exe` and a `pip` package, and can extract audio/video from thousands of sites beyond YouTube.\n\n### Why yt-dlp over youtube-dl\n\nyt-dlp's main focus is adding new features and patches while keeping up to date with the original youtube-dl project. Concretely, that means:\n\n- **Format sorting (`-S`)**: the default format-sorting behavior changed so higher resolution and better codecs are preferred over simply picking the largest bitrate, and `-S` lets you fully customize the sort order \u2014 this is the backbone of the MKV/1080p setup in the TL;DR above.\n- **SponsorBlock integration**: mark or remove sponsor segments in YouTube videos using the SponsorBlock API \u2014 no browser extension required.\n- Much faster development cadence \u2014 youtube-dl extractors frequently break when sites change; yt-dlp patches these far more quickly.\n- JS-challenge solving, PO tokens, and other modern anti-bot workarounds that youtube-dl does not implement.\n\n### Supported websites\n\nOfficially \"thousands,\" ranging from YouTube, Twitch, Vimeo, SoundCloud, TikTok, Twitter/X, Reddit, Bilibili, and Niconico to countless news sites, educational platforms, and live-streaming services. The canonical, always-current list lives at `yt-dlp --list-extractors` or `supportedsites.md` in the repo \u2014 do **not** trust any third-party \"supported sites\" list, since they go stale within weeks.\n\n### Key features\n\n- Merges separate video/audio streams via FFmpeg (needed because YouTube etc. deliver video and audio as separate DASH streams above 720p/\"pre-merged\" quality)\n- Playlist and channel downloading with item ranges\n- Subtitle download/embedding (manual and auto-generated)\n- Metadata, chapters, thumbnail embedding\n- Cookie import directly from browsers (no manual export needed)\n- Live-stream recording, including \"from the start\"\n- Format filtering/sorting language for very precise quality control\n- Plugin system for extending extractors and post-processors\n- Aria2c / external downloader integration for faster or resumable transfers\n\n### Legal and ethical considerations\n\nyt-dlp itself is legal open-source software. Whether downloading a specific piece of content is legal depends on **copyright law and the target platform's Terms of Service** in your jurisdiction \u2014 most streaming platforms' ToS prohibit downloading content you don't have explicit rights to. This guide does not provide legal advice; use yt-dlp for content you own, that is licensed under permissive terms (Creative Commons, public domain), or that you otherwise have the right to download (e.g., your own uploads, or explicit \"download\" permission from the creator).\n\n### Limitations\n\n- Cannot download DRM-protected streams (most paid streaming services \u2014 Netflix, Disney+, Spotify, etc. \u2014 are explicitly out of scope and unsupported by design).\n- Site extractors break whenever a platform changes its internals; you rely on the community shipping a fix, usually within days.\n- Livestream/DASH edge cases, geo-restrictions, and login walls can require extra configuration (cookies, proxies) covered in \u00a79 and \u00a716.\n- No official GUI \u2014 it's a CLI-first tool (see \u00a724 for third-party GUIs).\n\n---\n\n## 2. Installation\n\n```mermaid\nflowchart TD\n A[Choose install method] --> B{Do you want automaticupdates & PATH setup?}\n B -->|Yes, easiest| C[winget install yt-dlp.yt-dlp]\n B -->|Yes, I already use Scoop| D[scoop install yt-dlp]\n B -->|Yes, I already use Chocolatey| E[choco install yt-dlp]\n B -->|No, I want full control| F[Download yt-dlp.exe manually]\n B -->|I want the Python package /plugin ecosystem| G[pip install yt-dlp]\n F --> H[Place in a folder, e.g. C:\\yt-dlp]\n H --> I[Add folder to PATH]\n C --> J[Install FFmpeg]\n D --> J\n E --> J\n I --> J\n G --> J\n J --> K[Verify: yt-dlp -v --version]\n```\n\n### Standalone Binary (Recommended for most people)\n\nThis is the officially recommended method \u2014 a single `.exe`, no Python required.\n\n1. Go to the official releases page: **https://github.com/yt-dlp/yt-dlp/releases/latest**\n2. Under **Assets**, download `yt-dlp.exe` (the plain Windows build). There are also `yt-dlp_x86.exe` (32-bit) and `yt-dlp_win_arm64.exe` builds for niche systems.\n3. **Verifying authenticity**: yt-dlp release assets are signed. Each release includes a `SHA2-256SUMS` file and, for recent releases, GPG signatures (`SHA2-256SUMS.sig`) signed with the maintainers' keys published in the repo (`public.key`). To verify on Windows PowerShell:\n ```powershell\n Get-FileHash .\\yt-dlp.exe -Algorithm SHA256\n # Compare the output hash against the value in SHA2-256SUMS from the same release\n ```\n4. **Portable installation / folder structure**: create a dedicated folder, e.g. `C:\\yt-dlp\\`, and keep `yt-dlp.exe`, `ffmpeg.exe`, `ffprobe.exe`, and an optional `yt-dlp.conf` all in that same folder. This is the cleanest, fully portable setup \u2014 nothing touches the registry, and you can copy the whole folder to another PC.\n ```\n C:\\yt-dlp\\\n \u251c\u2500\u2500 yt-dlp.exe\n \u251c\u2500\u2500 ffmpeg.exe\n \u251c\u2500\u2500 ffprobe.exe\n \u2514\u2500\u2500 yt-dlp.conf (optional, see \u00a77)\n ```\n5. **Adding to PATH** (so you can run `yt-dlp` from any folder/terminal):\n - Press **Start**, search **\"Edit the system environment variables\"** \u2192 **Environment Variables\u2026**\n - Under **User variables**, select **Path** \u2192 **Edit** \u2192 **New** \u2192 paste `C:\\yt-dlp` \u2192 **OK** on every dialog.\n - Restart any open terminal windows (PATH changes don't apply to already-open sessions).\n6. **Updating**: `yt-dlp -U` self-updates the binary in place by downloading the newest release and replacing itself. This only works for the **standalone binary**, not for pip/winget/scoop/choco installs.\n - **When it doesn't work**: if `-U` fails with a permissions error, it's usually because the `.exe` lives in a protected folder (e.g. `Program Files`) without write access \u2014 move it to a user-writable folder like `C:\\yt-dlp` or your user profile. If it fails silently behind a corporate proxy/firewall, download the new release manually instead.\n\n### Winget\n\nWinget is Microsoft's official package manager, built into Windows 10 (1809+) and all Windows 11 versions.\n\n```powershell\n# Install\nwinget install yt-dlp.yt-dlp\n\n# Upgrade\nwinget upgrade yt-dlp.yt-dlp\n\n# Uninstall\nwinget uninstall yt-dlp.yt-dlp\n```\n\nThis is also documented directly on the official yt-dlp Installation wiki page as `winget install yt-dlp`, updated with `winget upgrade yt-dlp`. Winget automatically places the executable on PATH, so no manual PATH editing is required.\n\n### Scoop\n\nScoop installs command-line tools into your user profile without needing admin rights.\n\n```powershell\n# One-time: install Scoop itself, if you don't have it\nirm get.scoop.sh | iex\n\n# Install yt-dlp\nscoop install yt-dlp\n\n# Update (just yt-dlp)\nscoop update yt-dlp\n\n# Update everything Scoop manages\nscoop update *\n\n# Uninstall\nscoop uninstall yt-dlp\n```\n\nThe command is confirmed directly by the official wiki (`scoop update yt-dlp`).\n\n### Chocolatey\n\nChocolatey requires an elevated (administrator) PowerShell.\n\n```powershell\n# Install (run PowerShell as Administrator first)\nchoco install yt-dlp\n\n# Upgrade\nchoco upgrade yt-dlp\n\n# Uninstall\nchoco uninstall yt-dlp\n```\n\nConfirmed by the official wiki as `choco install yt-dlp`, with updates via `choco upgrade yt-dlp`. Note that the community Chocolatey package is third-party maintained (not published by the yt-dlp team directly), so it can lag a release or two behind \u2014 check the version before relying on brand-new features.\n\n### Python (pip)\n\nBest if you want the plugin ecosystem, want to pin a specific Python version, or are integrating yt-dlp into your own scripts as a library.\n\n1. **Install Python**: get the latest Python 3 from **python.org** (check **\"Add python.exe to PATH\"** during setup). As of the 2026.06.09 release, the minimum supported Python versions for related tooling were raised, and yt-dlp itself now recommends Python 3.11 or newer, since Python 3.10 reaches end-of-life in October 2026.\n2. **Install yt-dlp**:\n ```powershell\n py -m pip install -U \"yt-dlp[default]\"\n ```\n The `[default]` extra pulls in recommended optional dependencies (`mutagen`, `pycryptodomex`, `websockets`, `brotli`, `certifi`, etc.) for full feature support.\n3. **Updating**:\n ```powershell\n py -m pip install -U \"yt-dlp[default]\"\n ```\n4. **Virtual environments** (recommended if you also do Python development and don't want dependency conflicts):\n ```powershell\n py -m venv $env:USERPROFILE\\.venvs\\ytdlp\n & \"$env:USERPROFILE\\.venvs\\ytdlp\\Scripts\\Activate.ps1\"\n pip install -U \"yt-dlp[default]\"\n ```\n To run it without activating every time, call the venv's yt-dlp directly: `& \"$env:USERPROFILE\\.venvs\\ytdlp\\Scripts\\yt-dlp.exe\" URL`, or add an alias (see \u00a717).\n\n**Advantages vs. standalone `.exe`**: easy access to nightly/master builds (`pip install --pre -U yt-dlp` for prerelease builds, or install straight from the `master` branch tarball), simpler scripting/library use, easier plugin installs.\n\n**Disadvantages**: extra dependency (Python itself) to maintain and keep patched; slightly slower startup time than the compiled binary; more moving parts to break (venv path issues, PATH shadowing between multiple Python installs).\n\n### Summary comparison table\n\n| Method | Admin rights? | Auto PATH setup | Self-update command | Best for |\n|---|---|---|---|---|\n| Standalone `.exe` | No | Manual | `yt-dlp -U` | Full control, portable USB installs |\n| winget | No (user scope) | Yes | `winget upgrade yt-dlp.yt-dlp` | Most Windows 10/11 users |\n| Scoop | No | Yes | `scoop update yt-dlp` | Power users who like Scoop's ecosystem |\n| Chocolatey | Yes | Yes | `choco upgrade yt-dlp` | Admin-managed / enterprise machines |\n| pip | No | Yes (via Python Scripts dir) | `pip install -U yt-dlp[default]` | Scripting, plugins, nightly builds |\n\n---\n\n## 3. FFmpeg\n\n### Why FFmpeg is required\n\nYouTube (and many other sites) deliver anything above roughly 1080p \u2014 and often 1080p itself for the highest-efficiency codecs \u2014 as **separate** video-only and audio-only streams (DASH). YouTube streams 4K/8K as separate video and audio tracks, and FFmpeg is what merges them back together into one playable file. FFmpeg is also required for: audio extraction/re-encoding (MP3, FLAC, Opus, etc.), embedding thumbnails/subtitles/chapters into the final file, and remuxing between containers (MP4 \u21c4 MKV). Without it, yt-dlp can still download pre-merged low-quality formats, but you lose almost every \"advanced\" feature.\n\nyt-dlp's own documentation lists ffmpeg and ffprobe as required for merging separate video/audio files and for various post-processing tasks, and specifically warns: what you need is the ffmpeg *binary*, not the Python package of the same name (`pip install ffmpeg` does NOT give you what yt-dlp needs).\n\n### Downloading official Windows builds\n\nThe yt-dlp project maintains its own FFmpeg Windows builds at `yt-dlp/FFmpeg-Builds`, which are currently equivalent to upstream FFmpeg (no more custom patches applied). You have two good sources:\n\n- **yt-dlp/FFmpeg-Builds** (GitHub): `github.com/yt-dlp/FFmpeg-Builds/releases` \u2014 builds specifically tested against yt-dlp's use cases.\n- **gyan.dev** Windows builds (community-maintained, widely used, also distributed via `winget install Gyan.FFmpeg`): a `full` or `essentials` build is sufficient for yt-dlp.\n\nGrab the `win64` release build (a `.zip` or `.7z` archive).\n\n### Folder layout\n\nAfter extracting, you'll see something like:\n\n```\nffmpeg-release-full\\\n\u251c\u2500\u2500 bin\\\n\u2502 \u251c\u2500\u2500 ffmpeg.exe\n\u2502 \u251c\u2500\u2500 ffprobe.exe\n\u2502 \u2514\u2500\u2500 ffplay.exe\n\u251c\u2500\u2500 doc\\\n\u2514\u2500\u2500 presets\\\n```\n\nThe only two files yt-dlp actually needs are **`ffmpeg.exe`** and **`ffprobe.exe`** from the `bin\\` folder.\n\n### PATH configuration\n\nTwo options:\n\n1. **Add `bin\\` to PATH** (same steps as \u00a72's PATH instructions) \u2014 makes `ffmpeg`/`ffprobe` runnable from anywhere and lets yt-dlp auto-detect them.\n2. **Copy `ffmpeg.exe` and `ffprobe.exe` directly into your `C:\\yt-dlp\\` folder** next to `yt-dlp.exe` \u2014 no PATH edit needed; yt-dlp checks its own directory first.\n\n### Verifying installation\n\n```powershell\nffmpeg -version\nffprobe -version\n```\n\nBoth should print a version banner. If PowerShell says `ffmpeg is not recognized`, PATH wasn't applied (see \u00a719 Troubleshooting \u2192 PATH issues) or you're using a terminal window opened before the PATH change.\n\n### Common mistakes\n\n- Installing the `ffmpeg` **PyPI package** (`pip install ffmpeg`) instead of the actual binary \u2014 this Python package does nothing useful for yt-dlp.\n- Downloading a **32-bit** FFmpeg build on a 64-bit system (works, but noticeably slower for heavy re-encodes).\n- Extracting FFmpeg into `Downloads\\` and forgetting where it is \u2014 always move it to a permanent, deliberate folder before wiring up PATH.\n- Only adding the **top-level** extracted folder to PATH instead of the `bin\\` subfolder that actually contains the `.exe` files.\n\n### How yt-dlp detects FFmpeg\n\nyt-dlp looks for `ffmpeg`/`ffprobe` in this order: (1) the location you set with `--ffmpeg-location PATH` (either the exe's folder or the exe itself), (2) yt-dlp's own directory (useful for portable installs), (3) your system `PATH`. If you have multiple FFmpeg installs (e.g. one bundled with another app like OBS or Audacity), an old/incompatible one earlier in PATH can silently get picked up \u2014 use `--ffmpeg-location` explicitly to be sure, or check which one wins with `where ffmpeg` in PowerShell/CMD.\n\n### Using portable FFmpeg\n\n```powershell\nyt-dlp --ffmpeg-location \"C:\\yt-dlp\\ffmpeg.exe\" \"URL\"\n# or point at the containing folder\nyt-dlp --ffmpeg-location \"C:\\ffmpeg\\bin\" \"URL\"\n```\n\nPut this in your config file (\u00a77) so you never have to type it again.\n\n### Troubleshooting missing FFmpeg errors\n\n| Symptom | Cause | Fix |\n|---|---|---|\n| `WARNING: You have requested merging of multiple formats but ffmpeg is not installed` | FFmpeg not found on PATH or in yt-dlp's folder | Install FFmpeg (above) or pass `--ffmpeg-location` |\n| Downloads succeed but stay as separate `.f137` / `.f251` files | Same as above \u2014 no merge happened | Same fix; delete the leftover partial files and re-run |\n| `ffprobe not found`, metadata/duration missing | Only `ffmpeg.exe` was placed, `ffprobe.exe` forgotten | Copy `ffprobe.exe` alongside `ffmpeg.exe` |\n| `Postprocessing: Error opening output file` | Corrupt/incompatible FFmpeg build (rare 32-bit or ancient build) | Redownload a current `win64` build |\n\n---\n\n## 4. Windows Terminal: CMD vs. PowerShell vs. Windows Terminal\n\n**Windows Terminal** is just the modern *host application* (tabs, GPU rendering, profiles) \u2014 inside it you still run either **Command Prompt (cmd.exe)** or **PowerShell**. It's the recommended way to run yt-dlp day-to-day because it's fast, supports Unicode properly, and lets you keep multiple sessions in tabs.\n\n| | Command Prompt (cmd.exe) | PowerShell | Windows Terminal |\n|---|---|---|---|\n| Quoting | Double quotes `\"...\"` only | Double **or** single quotes | Depends on which shell tab you're in |\n| Variables | `%VARNAME%` | `$env:VARNAME` | Same as underlying shell |\n| Unicode filename support | Weak by default (needs `chcp 65001`) | Good | Good (host renders UTF-8 natively) |\n| Scripting | `.bat` | `.ps1` (far more powerful) | N/A \u2014 it's just the window |\n| Recommended for | Quick one-off commands | Automation, scripts, loops | Everyday driver, houses either shell |\n\n### Quoting rules\n\n- **PowerShell**: prefer **double quotes** for URLs/paths containing `$`-like characters that you don't want expanded, and single quotes when you want the string completely literal. Note that on Windows you may need to use double quotes instead of single quotes compared to Linux/macOS examples you'll find online \u2014 this trips up almost everyone copying commands from a Mac/Linux tutorial.\n ```powershell\n yt-dlp -f \"bv*+ba/b\" \"https://youtu.be/XXXXXXXXXXX\"\n ```\n- **CMD**: only double quotes work reliably; you cannot nest them, and `%` needs doubling (`%%`) inside batch files (but not when typed interactively).\n\n### Escaping characters\n\n- URLs with `&` (common in YouTube playlist URLs) **must** be quoted in both shells, or CMD/PowerShell will interpret `&` as a command separator and truncate the URL.\n ```powershell\n yt-dlp \"https://www.youtube.com/watch?v=XXXXXXXXXXX&list=PLxxxxxxxx\"\n ```\n- In PowerShell, a literal `$` inside double quotes needs a backtick: `` `$ ``. Inside single quotes, `$` is always literal.\n- Format selectors with square brackets (`[height<=1080]`) must be quoted in both shells \u2014 unquoted brackets can be misparsed.\n\n### File paths\n\n- Always quote paths with spaces: `-P \"C:\\Users\\Itachi\\My Videos\"`.\n- Both `\\` and `/` work as path separators in yt-dlp's own path-handling, but native Windows tools (and copy-paste from Explorer) will give you `\\`.\n- Prefer `~` or `%USERPROFILE%`/`$env:USERPROFILE` over hardcoding `C:\\Users\\yourname\\...` so configs are portable across machines.\n\n### Unicode filenames\n\nyt-dlp handles Unicode titles (Japanese, Korean, emoji, etc.) correctly by default. Two Windows-specific gotchas:\n\n1. **CMD's legacy code page** can mis-render Unicode in the terminal *display* (cosmetic only \u2014 the actual saved filename is still correct). Run `chcp 65001` first, or just use PowerShell/Windows Terminal, which handles UTF-8 natively.\n2. **NTFS forbids certain characters** in filenames (`\\ / : * ? \" < > |`) that are legal in video titles. yt-dlp automatically sanitizes these on Windows by default \u2014 see \u00a78 for how this affects your output templates.\n\n### Environment variables\n\n| Shell | Syntax | Example |\n|---|---|---|\n| CMD | `%VAR%` | `%USERPROFILE%\\Videos` |\n| PowerShell | `$env:VAR` | `$env:USERPROFILE\\Videos` |\n| Inside yt-dlp options (`-o`, `-P`, `--config-locations`, etc.) | `%VAR%` **or** `${VAR}` | yt-dlp allows using UNIX-style `${VARIABLE}` syntax on Windows for path-like options such as `--output` and `--config-locations` |\n\nOn Windows, `${USERPROFILE}` generally points to `C:\\Users\\` and `${APPDATA}` to `${USERPROFILE}\\AppData\\Roaming` \u2014 these are the two variables you'll use constantly for config files and output folders.\n\n---\n\n## 5. Basic Usage\n\n*(Beginner level \u2014 this section assumes yt-dlp and FFmpeg are already installed and on PATH.)*\n\n### Downloading a single video\n\n```powershell\nyt-dlp \"https://www.youtube.com/watch?v=XXXXXXXXXXX\"\n```\n\n### Downloading a playlist\n\n```powershell\nyt-dlp \"https://www.youtube.com/playlist?list=PLxxxxxxxxxxxxxxxx\"\n```\n\n### Downloading a channel (all uploads)\n\n```powershell\nyt-dlp \"https://www.youtube.com/@ChannelName/videos\"\n```\n\n### Downloading a livestream archive (already-ended stream, VOD)\n\n```powershell\nyt-dlp \"https://www.youtube.com/watch?v=LIVESTREAM_ID\"\n```\n\nFor a **currently live** stream, yt-dlp will wait and record from the current point unless you add `--live-from-start` to capture from the beginning (site support required; YouTube supports this).\n\n```powershell\nyt-dlp --live-from-start \"https://www.youtube.com/watch?v=LIVE_ID\"\n```\n\n### Downloading Shorts\n\nShorts are just regular videos under a different URL path \u2014 no special flag needed:\n\n```powershell\nyt-dlp \"https://www.youtube.com/shorts/XXXXXXXXXXX\"\n```\n\n### Audio extraction\n\n```powershell\nyt-dlp -x --audio-format mp3 \"URL\"\n```\n\n`-x` (`--extract-audio`) downloads the best audio-only stream and converts it (via FFmpeg) to the format given by `--audio-format`. See \u00a712 for all supported formats.\n\n### Metadata, thumbnails, chapters (all beginner-friendly flags)\n\n```powershell\nyt-dlp --embed-metadata --embed-thumbnail --embed-chapters \"URL\"\n```\n\n### Subtitles\n\n```powershell\n# Manual (human-written) subtitles only, English\nyt-dlp --write-subs --sub-langs en \"URL\"\n\n# Auto-generated subtitles (YouTube's ASR captions)\nyt-dlp --write-auto-subs --sub-langs en \"URL\"\n```\n\n### Resuming interrupted downloads\n\nyt-dlp resumes partial downloads **by default** \u2014 if a `.part` file exists from a previous run, re-running the same command continues instead of restarting. To explicitly disable/force this:\n\n```powershell\nyt-dlp --continue \"URL\" # (default behavior, explicit)\nyt-dlp --no-continue \"URL\" # force restart from scratch\n```\n\n### Playlist handling basics\n\n```powershell\n# Only the 5th item\nyt-dlp --playlist-items 5 \"PLAYLIST_URL\"\n\n# A range\nyt-dlp --playlist-items 1-10 \"PLAYLIST_URL\"\n\n# Skip the first 3 (start at #4)\nyt-dlp --playlist-start 4 \"PLAYLIST_URL\"\n```\n\nMore playlist power-tools are in \u00a711.\n\n---\n\n## 6. Format Selection\n\n*(Intermediate/Advanced \u2014 this is the single most powerful part of yt-dlp.)*\n\n### `-F` \u2014 list all available formats\n\nAlways run this first when you want a *specific* quality/codec:\n\n```powershell\nyt-dlp -F \"URL\"\n```\n\nOutput looks like:\n\n```\nID EXT RESOLUTION FPS CH \u2502 FILESIZE TBR PROTO \u2502 VCODEC VBR ACODEC ABR ASR MORE INFO\n137 mp4 1920x1080 30 \u2502 ~120.5MiB ... https \u2502 avc1.640028 ... video only\n251 webm audio only \u2502 ~ 8.1MiB ... https \u2502 opus 160k\n```\n\n- `bv`/`bestvideo` selectors work with **video-only** rows.\n- `ba`/`bestaudio` selectors work with **audio-only** rows.\n- Combined (\"pre-merged\") rows have both a VCODEC and ACODEC filled in.\n\n### `-f` \u2014 select a format\n\n```powershell\n# Download and merge the best video-only + best audio-only,\n# falling back to best combined if separate streams aren't offered\nyt-dlp -f \"bv+ba/b\" \"URL\"\n\n# Same, but skip merging if the video already has audio built in\nyt-dlp -f \"bv*+ba/b\" \"URL\"\n```\n\nThese two idiomatic patterns \u2014 `bv+ba/b` and `bv*+ba/b` \u2014 are the officially documented recommended selectors, and running yt-dlp with no `-f` flag at all defaults to the same behavior.\n\nCommon filtered selectors:\n\n```powershell\nyt-dlp -f \"bv*[height<=1080]+ba/b[height<=1080]\" \"URL\" # cap at 1080p\nyt-dlp -f \"bv*[height<=2160]+ba/b[height<=2160]\" \"URL\" # cap at 4K\nyt-dlp -f 137 \"URL\" # specific format ID from -F\nyt-dlp -f \"22\" \"URL\" # specific pre-merged format ID\n```\n\nYou can also select by codec:\n\n```powershell\nyt-dlp -f \"bv*[vcodec^=avc1]+ba[acodec^=mp4a]\" \"URL\" # force H.264 video + AAC audio\nyt-dlp -f \"bv*[vcodec^=av01]+ba\" \"URL\" # force AV1 video\n```\n\nGrouping with parentheses lets you fall back between whole containers: `-f \"(mp4,webm)[height<480]\"` downloads the best pre-merged mp4 or webm format under 480p.\n\n### `-S` \u2014 format sorting (the recommended approach over rigid `-f` filters)\n\nInstead of hard *filtering*, `-S` re-orders yt-dlp's own \"best\" ranking, so you still get automatic fallback if your preferred codec/resolution isn't available. The general syntax is `--format-sort field1,field2,...`, and you can force your custom order to override the built-in defaults entirely with `--format-sort-force`.\n\nKey sortable fields:\n\n| Field | Meaning | Default preference order |\n|---|---|---|\n| `res` | Resolution (height) | Higher is better |\n| `fps` | Frame rate | Higher is better |\n| `vcodec` | Video codec | av01 > vp9.2 > vp9 > h265 > h264 > vp8 > h263 > theora > other |\n| `acodec` | Audio codec | flac/alac > wav/aiff > opus > vorbis > aac > mp4a > mp3 > ac4 > eac3 > ac3 > dts > other |\n| `hdr` | Dynamic range | SDR preferred over HDR by default (`hdr:12` \u2014 Dolby Vision specifically is *not* preferred by default since DV isn't fully compatible with most devices) |\n| `ext` | Container extension | Video: mp4 > mov > webm > flv > other (webm wins instead if `--prefer-free-formats` is set) |\n| `size`, `br` | Filesize / bitrate | Higher is better |\n| `proto` | Download protocol | https/ftps > http/ftp > m3u8_native/m3u8 > http_dash_segments > websocket_frag > f4f/f4m |\n\nThe full built-in default sort order (when you don't specify `-S` at all) is: `lang,quality,res,fps,hdr:12,vcodec,channels,acodec,size,br,asr,proto,ext,hasaud,source,id`. `hasvid` and `ie_pref` always take top priority regardless of your custom order, unless you pass `--format-sort-force`.\n\n**Practical examples:**\n\n```powershell\n# Prefer H.264 video and AAC audio (max device compatibility), any resolution\nyt-dlp -S \"vcodec:h264,acodec:aac\" -f \"bv+ba/b\" \"URL\"\n\n# Cap resolution at 1080p while still sorting by codec preference (this guide's default)\nyt-dlp -S \"res:1080,vcodec:h264,acodec:aac\" -f \"bv+ba/b\" \"URL\"\n\n# Prefer smallest file size instead of best quality (rare, but useful for slow connections)\nyt-dlp -f best -S \"+size,+br,+res,+fps\" \"URL\"\n```\n\nNote: if you use `-f worst`, yt-dlp picks the format that's worst in *every* respect at once, which usually isn't what you want \u2014 `-S \"+size,+br,+res,+fps\"` with `-f best` is the documented, better alternative for \"smallest reasonable file.\"\n\n### Merging & container selection: MP4 vs. MKV\n\n```powershell\n--merge-output-format mkv # container used ONLY when a merge is actually required\n--remux-video mkv # additionally re-container a video that's already combined\n```\n\n`--merge-output-format` accepts one of `mkv, mp4, ogg, webm, flv`, and is ignored entirely if no merge is required in the first place \u2014 this is why the TL;DR config also sets `--remux-video mkv`: it guarantees MKV even for videos that came pre-merged and never needed FFmpeg's merger.\n\n**Why this guide defaults to MKV over MP4:**\n\n| | MKV | MP4 |\n|---|---|---|\n| Codec flexibility | Accepts virtually any video/audio codec combo (AV1, VP9, Opus, etc.) without re-encoding | Stricter \u2014 some codec combos (e.g. VP9+Opus) either don't fit or need re-encoding to be \"valid\" MP4 |\n| Chapters/subtitles/multiple audio tracks | Native, robust support | Supported but more finicky |\n| Compatibility with old hardware/software (TVs, some phones, video editors) | Weaker | Much stronger \u2014 nearly universal |\n| Streaming-friendly / web players | Weaker | Stronger |\n\n**Rule of thumb**: MKV if you're archiving on a PC/NAS and want zero quality loss from container juggling (this guide's default); MP4 if the file needs to play on a smart TV, phone, or be re-uploaded/edited elsewhere \u2014 in which case swap `mkv` for `mp4` in the config from the TL;DR.\n\nTo specify multiple fallback rules for `--remux-video`/`--recode-video`: e.g. `\"aac>m4a/mov>mp4/mkv\"` remuxes aac to m4a, mov to mp4, and anything else to mkv.\n\n### \"Or the original\" \u2014 grabbing untouched maximum quality\n\nSometimes you don't want the 1080p cap \u2014 you want whatever the uploader actually published, uncapped:\n\n```powershell\nyt-dlp -f \"bv*+ba/b\" -S \"res,vcodec:h264,acodec:aac\" --merge-output-format mkv \"URL\"\n```\n\nDropping the `:1080` from `res` removes the height cap entirely while keeping your codec preference \u2014 yt-dlp will grab the highest resolution the site actually offers (4K/8K if available) and merge it into MKV.\n\n---\n\n## 7. Configuration Files\n\n*(Intermediate)*\n\n### Locations on Windows, in load order\n\nyt-dlp reads config files from multiple locations and merges them (later ones can override earlier ones); **command-line arguments always win over any config file.**\n\n| Priority | Location | Notes |\n|---|---|---|\n| 1. Command line | n/a | Always wins |\n| 2. Portable config | `yt-dlp.conf` next to `yt-dlp.exe` | Recommended specifically for portable installations \u2014 the config travels with the executable |\n| 3. User config (primary) | `%APPDATA%\\yt-dlp\\config.txt` | The usual/most common location on Windows |\n| 4. User config (alt) | `%APPDATA%\\yt-dlp\\config` (no extension) | Also read; `config.txt` and `config` are both valid names |\n| 5. System config | none by default on Windows (Unix has `/etc/yt-dlp.conf`) | Rare to use on Windows |\n\nOn Windows, `~` resolves to `${HOME}` if it's set, or otherwise to `${USERPROFILE}` / `${HOMEDRIVE}${HOMEPATH}`.\n\n### Confirming what actually loaded\n\n```powershell\nyt-dlp -v \"URL\" 2>&1 | Select-String -Pattern \"config\"\n```\n\nRunning any command with `-v` (verbose) prints the paths of every config file yt-dlp loaded, near the top of the output \u2014 this is the fastest way to debug \"my config isn't applying\" issues.\n\n### `--config-locations` \u2014 multiple/custom config files\n\n```powershell\n# Load one specific config file only, ignoring the default search\nyt-dlp --config-locations \"C:\\yt-dlp\\music.conf\" \"URL\"\n\n# Combine several\nyt-dlp --config-locations \"C:\\yt-dlp\\base.conf\" --config-locations \"C:\\yt-dlp\\mkv.conf\" \"URL\"\n```\n\n`--config-locations` can also be used *inside* another config file to chain-load additional configs. This is how power users build \"profiles\" \u2014 e.g. a `base.conf` with paths/archive settings, plus a swappable `audio.conf` or `mkv.conf` for per-task overrides. A tidy way to invoke these from PowerShell is wrapping them in a function, e.g. `function yt-music { yt-dlp --config-locations ~/.config/yt-dlp/music.conf $args }` (translate the path to a Windows one \u2014 see \u00a717 for a full PowerShell profile example).\n\nTo bypass **all** config files for one run: `yt-dlp --ignore-config -f best \"URL\"` (also documented as the way to override configs on a per-command basis).\n\n### Fully commented ideal Windows configuration\n\nSave this as `%APPDATA%\\yt-dlp\\config.txt`:\n\n```ini\n# ============================================================\n# yt-dlp configuration \u2014 Windows\n# Location: %APPDATA%\\yt-dlp\\config.txt\n# One option per line, written exactly as on the command line\n# (without the leading \"yt-dlp\"). Lines starting with # are comments.\n# ============================================================\n\n# ---- Format & container: MKV, cap 1080p, best audio -------\n# Prefer 1080p, H.264 video (max compatibility), AAC audio\n-S \"res:1080,vcodec:h264,acodec:aac\"\n# Only used if a merge is actually required\n--merge-output-format mkv\n# Force MKV even for videos that arrive pre-merged\n--remux-video mkv\n\n# ---- Output location & naming ------------------------------\n-P \"~/Videos/yt-dlp\"\n-o \"%(uploader)s/%(title)s [%(id)s].%(ext)s\"\n\n# ---- Metadata / thumbnails / chapters -----------------------\n--embed-metadata\n--embed-thumbnail\n--embed-chapters\n--add-metadata\n\n# ---- Subtitles ------------------------------------------------\n--write-subs\n--sub-langs \"en.*\"\n--embed-subs\n\n# ---- Don't re-download things you already have ---------------\n--download-archive \"~/Videos/yt-dlp/archive.txt\"\n\n# ---- Networking / reliability ---------------------------------\n--retries 10\n--fragment-retries 10\n--concurrent-fragments 4\n\n# ---- Misc quality-of-life --------------------------------------\n--no-mtime # keep the actual download date, not the upload date, as file timestamp\n--restrict-filenames # ASCII-only filenames (optional; remove if you want Unicode titles as-is)\n```\n\nRemove `--restrict-filenames` if you're fine with Unicode characters directly in filenames (modern Windows/NTFS handles them fine \u2014 see \u00a74 and \u00a720).\n\n---\n\n## 8. Output Templates\n\n*(Intermediate)*\n\n### Template syntax basics\n\nOutput templates use `%(fieldname)s` (string), `%(fieldname)d` (integer), or `%(fieldname)05d` (zero-padded integer) syntax, set with `-o`/`--output`.\n\n```powershell\nyt-dlp -o \"%(title)s.%(ext)s\" \"URL\"\n```\n\n### Commonly used fields\n\n| Field | Meaning |\n|---|---|\n| `%(title)s` | Video title |\n| `%(id)s` | Unique video ID |\n| `%(ext)s` | File extension (set automatically \u2014 never hardcode this) |\n| `%(uploader)s` | Channel/uploader name |\n| `%(upload_date)s` | `YYYYMMDD` |\n| `%(playlist)s` | Playlist name (empty if not part of one) |\n| `%(playlist_index)s` | Position within playlist |\n| `%(duration)s` / `%(duration_string)s` | Length in seconds / `HH:MM:SS` |\n| `%(resolution)s` | e.g. `1920x1080` |\n| `%(channel)s` | Channel name (site-dependent, may differ from uploader) |\n\n### Date formatting\n\n```powershell\nyt-dlp -o \"%(upload_date>%Y-%m-%d)s - %(title)s.%(ext)s\" \"URL\"\n```\n\nThe `>` syntax reformats a `strftime`-compatible field \u2014 `upload_date` is normally `YYYYMMDD`, and `>%Y-%m-%d` converts it to `2026-07-14`-style.\n\n### Nested folders / organization by playlist and channel\n\n```powershell\n# Organize by uploader, then playlist name if present\nyt-dlp -o \"%(uploader)s/%(playlist|Singles)s/%(title)s [%(id)s].%(ext)s\" \"URL\"\n```\n\nThe `|default` syntax (`%(playlist|Singles)s`) substitutes a fallback value (\"Singles\") when the field is empty \u2014 handy for videos that aren't part of any playlist.\n\nA common full pattern for a well-organized archive is `-o \"%(uploader)s/%(playlist|)s/%(upload_date>%Y-%m-%d)s - %(title)s [%(id)s].%(ext)s\"`.\n\n### Filename sanitization & Windows filename limitations\n\nyt-dlp **automatically sanitizes** filenames on Windows, stripping/replacing the characters NTFS forbids (`\\ / : * ? \" < > |`) and trimming trailing dots/spaces. Two extra flags matter here:\n\n- `--restrict-filenames`: forces ASCII-only, replaces spaces with underscores, strips special characters more aggressively \u2014 safest for scripts, USB drives formatted FAT32, or cross-platform syncing (e.g. via OneDrive to a Mac).\n- `--windows-filenames`: forces Windows-safe sanitization rules even when running yt-dlp on Linux/macOS (useful if you're producing files that will later be copied to a Windows machine); on Windows itself this is already the default behavior.\n\n**Path length**: classic Windows paths are capped at 260 characters (`MAX_PATH`) unless long-path support is enabled (see \u00a720). Long, deeply-nested `-o` templates (playlist name + uploader + long title) can hit this limit \u2014 if downloads randomly fail with a \"file not found\"/\"cannot create file\" error, this is usually why.\n\n### Practical examples\n\n```powershell\n# Flat, simple\nyt-dlp -o \"%(title)s [%(id)s].%(ext)s\" \"URL\"\n\n# By channel\nyt-dlp -o \"%(uploader)s/%(title)s.%(ext)s\" \"URL\"\n\n# By channel + upload year\nyt-dlp -o \"%(uploader)s/%(upload_date>%Y)s/%(title)s.%(ext)s\" \"URL\"\n\n# Playlist, numbered\nyt-dlp -o \"%(playlist)s/%(playlist_index)03d - %(title)s.%(ext)s\" \"PLAYLIST_URL\"\n\n# Audio library style\nyt-dlp -x --audio-format flac -o \"%(artist|uploader)s/%(album|Singles)s/%(title)s.%(ext)s\" \"URL\"\n```\n\n---\n\n## 9. Authentication\n\n*(Intermediate/Advanced)*\n\n### Browser cookies (`--cookies-from-browser`) \u2014 recommended method\n\nThis is the officially recommended way to authenticate on Windows \u2014 no manual cookie export needed:\n\n```powershell\nyt-dlp --cookies-from-browser chrome \"URL\"\nyt-dlp --cookies-from-browser firefox \"URL\"\nyt-dlp --cookies-from-browser edge \"URL\"\nyt-dlp --cookies-from-browser brave \"URL\"\n```\n\nSupported browser keywords include `brave`, `chrome`, `chromium`, `edge`, `firefox`, `opera`, `safari`, `vivaldi`, `whale`. On Windows, the Chromium-based browsers (Chrome/Edge/Brave/etc.) encrypt their cookie store using Windows DPAPI, tied to your Windows user account \u2014 yt-dlp decrypts it automatically as long as it's run under the *same* Windows user and the browser isn't set to a non-default profile without specifying it.\n\n**Selecting a specific profile / keyring:**\n\n```powershell\nyt-dlp --cookies-from-browser \"chrome:Profile 2\" \"URL\"\n```\n\n**Important caveat**: close the browser (or at least the relevant profile) before running yt-dlp \u2014 Chromium-based browsers lock the cookie database file while running, which can cause `--cookies-from-browser` to fail or grab stale cookies.\n\n### Exported cookie files (`--cookies`)\n\nIf you'd rather export cookies manually (e.g. using a browser extension like \"Get cookies.txt\"), in Netscape format:\n\n```powershell\nyt-dlp --cookies \"C:\\yt-dlp\\cookies.txt\" \"URL\"\n```\n\nThis avoids the \"browser must be closed\" issue and works well for scheduled tasks that run while you're actively using your browser (see \u00a717).\n\n### Login sessions / private videos / members-only content\n\nFor content requiring a logged-in session (private videos shared with your account, YouTube members-only posts, etc.), `--cookies-from-browser` using a session where you're already logged in is the standard approach \u2014 yt-dlp does **not** have a general-purpose username/password login for most sites (a few sites support `--username`/`--password`/`--netrc`, but YouTube specifically does not accept direct credentials \u2014 Google blocks programmatic logins).\n\n### Age-restricted videos\n\nAge-gated YouTube videos generally require a logged-in, age-verified account's cookies (`--cookies-from-browser`) to bypass \u2014 there's no separate \"age flag.\"\n\n### Authentication limitations\n\n- Cookies **expire** \u2014 if downloads that previously worked start failing with 403s or \"private video\" errors, re-export/re-grab cookies from a fresh browser session.\n- Google/YouTube actively fight automated cookie extraction; if a site changes its auth flow, this can break until yt-dlp ships a patch \u2014 check `github.com/yt-dlp/yt-dlp/issues` for current known issues before assuming your setup is broken.\n- 2FA-protected accounts: log in normally in the browser first (2FA happens there), then point yt-dlp at that browser's cookies \u2014 yt-dlp itself never handles 2FA prompts.\n- Never share `cookies.txt` \u2014 it grants full account session access to whoever has the file.\n\n---\n\n## 10. Batch Downloads\n\n*(Beginner/Intermediate)*\n\n### URL text files\n\n```powershell\nyt-dlp -a \"C:\\yt-dlp\\urls.txt\"\n```\n\nWhere `urls.txt` has one URL per line; lines starting with `#`, `;`, or `]` are treated as comments and skipped.\n\n### Download archives (avoid re-downloading)\n\n```powershell\nyt-dlp --download-archive \"C:\\yt-dlp\\archive.txt\" \"PLAYLIST_URL\"\n```\n\nyt-dlp records every successfully downloaded video ID in `archive.txt`. Re-running the exact same command later \u2014 e.g. against a channel that's gained new uploads \u2014 will **skip everything already in the archive** and only fetch new videos. This is the backbone of \"incremental\" channel/playlist syncing.\n\n### Incremental downloads (channel/playlist sync pattern)\n\n```powershell\nyt-dlp --download-archive \"archive.txt\" -o \"%(uploader)s/%(title)s.%(ext)s\" \"https://www.youtube.com/@ChannelName/videos\"\n```\n\nRun this same command on a schedule (\u00a717) \u2014 each run only pulls what's new since the last run.\n\n### Scheduled downloads / automation\n\nCovered fully in \u00a717 (Windows Task Scheduler, `.ps1` scripts).\n\n---\n\n## 11. Playlists\n\n*(Intermediate)*\n\n### Partial downloads / range selection\n\n```powershell\nyt-dlp --playlist-items 1,3,5-10 \"PLAYLIST_URL\"\n```\n\n`--playlist-items` accepts individual indices and ranges combined with commas, e.g. `1,3,5-10`.\n\n### Reverse order\n\n```powershell\nyt-dlp --playlist-reverse \"PLAYLIST_URL\"\n```\n\nThis downloads the playlist starting from the last item instead of the first \u2014 useful for playlists that list newest-first, when you want chronological download order.\n\n### Skipping duplicates across runs\n\nCombine `--download-archive` (see \u00a710) with a stable output template \u2014 the archive is what actually prevents duplicate downloads; the output template just keeps files organized.\n\n### Updating playlists efficiently\n\nThe efficient pattern for \"give me only what's new since last time\":\n\n```powershell\nyt-dlp --download-archive \"archive.txt\" --playlist-reverse \"PLAYLIST_URL\"\n```\n\n`--playlist-reverse` combined with an archive means yt-dlp processes oldest-to-newest and skips everything already recorded \u2014 new uploads simply get appended at the end of each future run.\n\n### Skipping already-downloaded items without a full archive scan\n\n```powershell\nyt-dlp --break-on-existing --download-archive \"archive.txt\" \"PLAYLIST_URL\"\n```\n\n`--break-on-existing` stops processing the *rest* of the playlist as soon as it hits the first already-archived video \u2014 much faster for large channels where you know new content is always added at the top.\n\n---\n\n## 12. Audio Downloads\n\n*(Beginner/Intermediate)*\n\n### Supported audio formats\n\n`--audio-format` currently supports: `best` (default, no re-encode), `aac`, `alac`, `flac`, `m4a`, `mp3`, `opus`, `vorbis`, `wav`.\n\n```powershell\nyt-dlp -x --audio-format mp3 \"URL\"\nyt-dlp -x --audio-format flac \"URL\"\nyt-dlp -x --audio-format opus \"URL\"\nyt-dlp -x --audio-format aac \"URL\"\nyt-dlp -x --audio-format wav \"URL\"\nyt-dlp -x --audio-format m4a \"URL\"\n```\n\n### Which format should you actually pick?\n\n| Format | Type | When to use |\n|---|---|---|\n| `opus` | Lossy, modern | **Best quality-per-bit** \u2014 matches what YouTube usually delivers natively, so `-x --audio-format opus` often needs **zero re-encoding** (fastest, no quality loss from transcoding) |\n| `m4a`/`aac` | Lossy | Best universal device compatibility (iPhones, car stereos, older hardware) |\n| `mp3` | Lossy | Maximum compatibility with very old software; avoid unless you specifically need it \u2014 re-encoding to MP3 from Opus/AAC source loses quality |\n| `flac`/`wav` | Lossless | **Do not** meaningfully improve quality over a lossy YouTube source (YouTube audio is lossy at the source) \u2014 only useful if you plan to further edit/process the audio and want a lossless *intermediate* file |\n\n### Quality settings\n\n```powershell\nyt-dlp -x --audio-format mp3 --audio-quality 0 \"URL\" # 0 = best VBR\nyt-dlp -x --audio-format mp3 --audio-quality 320K \"URL\" # explicit CBR bitrate\n```\n\n`--audio-quality` takes a value between 0 (best) and 10 (worst) for VBR, or a specific bitrate like `128K`; the default is `5`. For best-audio-always, `--audio-quality 0` is the setting used throughout this guide's \"best audio\" default.\n\n### Metadata & thumbnail embedding\n\n```powershell\nyt-dlp -x --audio-format opus --audio-quality 0 --embed-metadata --embed-thumbnail -o \"%(artist|uploader)s - %(title)s.%(ext)s\" \"URL\"\n```\n\nNote: thumbnail embedding into `opus`/`flac` containers is fully supported via FFmpeg, but not every music player renders embedded art from every container equally well \u2014 `m4a`/`mp3` have the broadest player support for embedded cover art.\n\n---\n\n## 13. Subtitle Downloads\n\n*(Beginner/Intermediate)*\n\n### Manual (human-written) subtitles\n\n```powershell\nyt-dlp --write-subs --sub-langs en \"URL\"\n```\n\n### Auto-generated subtitles\n\n```powershell\nyt-dlp --write-auto-subs --sub-langs en \"URL\"\n```\n\n### Multiple languages\n\n```powershell\nyt-dlp --write-subs --sub-langs \"en,ja,es\" \"URL\"\n```\n\n`--sub-langs` accepts regex, e.g. `\"en.*,ja\"` matches `en`, `en-US`, `en-GB`, etc. plus `ja`, and you can prefix a language with `-` to exclude it, e.g. `\"all,-live_chat\"`.\n\n### Listing what's actually available first\n\n```powershell\nyt-dlp --list-subs \"URL\"\n```\n\n### Embedding subtitles directly into the video file\n\n```powershell\nyt-dlp --write-subs --sub-langs en --embed-subs \"URL\"\n```\n\nEmbedding into MKV supports essentially any subtitle format without conversion; MP4 embedding is pickier (generally requires `mov_text`/SRT-compatible tracks, which yt-dlp handles automatically via FFmpeg conversion when needed).\n\n### Converting subtitle formats\n\n```powershell\nyt-dlp --write-subs --sub-format srt --sub-langs en \"URL\"\n# or convert whatever was downloaded afterward\nyt-dlp --write-subs --sub-langs en --convert-subs srt \"URL\"\n```\n\n`--sub-format` accepts a preference list separated by `/`, e.g. `\"srt\"` or `\"ass/srt/best\"`.\n\n---\n\n## 14. Metadata\n\n*(Intermediate)*\n\n### Embedding metadata into the file\n\n```powershell\nyt-dlp --embed-metadata \"URL\"\n```\n\nWrites title, uploader, description, upload date, etc. into the container's metadata tags (readable by most media players and file managers).\n\n### Chapters\n\n```powershell\nyt-dlp --embed-chapters \"URL\"\n```\n\nPulls YouTube's chapter markers (from the description timestamps or the official chapters feature) directly into the file as navigable chapter points.\n\n### Description as a separate file\n\n```powershell\nyt-dlp --write-description \"URL\"\n```\n\n### Comments\n\n```powershell\nyt-dlp --write-comments \"URL\"\n```\n\nSaves the video's comment section into the `.info.json` (see below) \u2014 can be slow on videos with thousands of comments; combine with `--max-comments` to cap it, e.g. `--max-comments 500`.\n\n### Full JSON metadata dump\n\n```powershell\nyt-dlp --write-info-json \"URL\"\n```\n\nWrites a `.info.json` sidecar file with essentially everything yt-dlp knows about the video \u2014 every field usable in output templates, full format list, etc. Extremely useful for archival/scripting purposes. Use `--no-write-info-json` (or just omit the flag) if you don't want the extra file cluttering your download folder.\n\n### SponsorBlock as metadata\n\nCovered fully in \u00a715 \u2014 SponsorBlock chapters can be embedded the same way as regular chapters.\n\n---\n\n## 15. SponsorBlock\n\n*(Intermediate)*\n\nyt-dlp integrates directly with the community-run [SponsorBlock](https://sponsor.ajay.app/) database (originally a browser extension) to mark or cut sponsor segments, intros, outros, and other non-content sections from YouTube videos \u2014 this is an officially listed core feature of yt-dlp itself, no extension required.\n\n### Installation / requirements\n\nNo separate install \u2014 it's built into yt-dlp. FFmpeg is required for the `--sponsorblock-remove` variant (which actually cuts the video), but not for `--sponsorblock-mark` (which only adds chapter markers you can skip manually in your player).\n\n### Marking segments as chapters (non-destructive, recommended default)\n\n```powershell\nyt-dlp --sponsorblock-mark all \"URL\"\n```\n\nThis adds chapter markers for each detected segment type, letting you skip them manually in any player that supports chapters (MKV/MP4 with `--embed-chapters`, or most modern video players) \u2014 nothing is deleted from the file.\n\n### Automatically removing segments (destructive \u2014 cuts the video)\n\n```powershell\nyt-dlp --sponsorblock-remove sponsor,selfpromo,interaction \"URL\"\n```\n\nThis re-encodes the affected sections out of the file entirely via FFmpeg \u2014 slower (requires re-encoding around cut points) and **cannot be undone** later, so use `--sponsorblock-mark` if you're unsure.\n\n### Categories\n\n| Category | Meaning |\n|---|---|\n| `sponsor` | Paid promotion segments |\n| `selfpromo` | Unpaid self-promotion (merch, other channels, etc.) |\n| `interaction` | \"Like and subscribe\" reminders |\n| `intro` | Channel intro/intro animation |\n| `outro` | Endcards/outro |\n| `preview` | Recap/preview of upcoming content |\n| `music_offtopic` | Non-music sections in music videos |\n| `filler` | Tangential filler content |\n| `poi_highlight` | Highlight/point-of-interest markers |\n| `all` | All of the above |\n\n### Combining mark + remove selectively\n\n```powershell\nyt-dlp --sponsorblock-mark all --sponsorblock-remove sponsor,interaction \"URL\"\n```\n\nMarks everything as chapters, but only physically removes the `sponsor` and `interaction` categories \u2014 the rest stay as skippable chapters.\n\n### Limitations\n\n- Only works on **YouTube** \u2014 SponsorBlock's database doesn't cover other sites.\n- Coverage depends entirely on community submissions \u2014 brand-new or low-view videos may have zero segments logged, so nothing gets marked/removed even if sponsor content is present.\n- `--sponsorblock-remove` re-encodes near cut points (to keep cuts frame-accurate), so it's meaningfully slower than a straight download and can introduce a tiny quality dip right at the cut boundary \u2014 `--sponsorblock-mark` avoids this entirely.\n\n---\n\n## 16. Advanced Features\n\n*(Advanced)*\n\n### Download archive\n\nCovered in \u00a710/\u00a711 \u2014 `--download-archive FILE.txt`.\n\n### Rate limiting\n\n```powershell\nyt-dlp --limit-rate 5M \"URL\" # cap at 5 MB/s\nyt-dlp --limit-rate 500K \"URL\" # cap at 500 KB/s\n```\n\nUseful to avoid saturating your connection during large batch jobs, or to reduce the odds of being rate-limited/flagged by aggressive rate limits on the source site.\n\n### Retries\n\n```powershell\nyt-dlp --retries 10 --fragment-retries 10 \"URL\"\n```\n\n`--retries` covers whole-download retry attempts on transient network failures; `--fragment-retries` covers individual DASH/HLS fragment retries within a single download. `--retries infinite` and `--fragment-retries infinite` are also valid for unattended long-running jobs.\n\n### Concurrent fragments\n\n```powershell\nyt-dlp --concurrent-fragments 4 \"URL\"\n```\n\nDownloads up to N fragments of a DASH/HLS stream in parallel \u2014 can meaningfully speed up downloads of long/high-bitrate videos on fast connections. Going much above 4\u20138 usually hits diminishing returns and increases the odds of being rate-limited by the source server.\n\n### Sleep intervals (politeness / avoiding rate limits)\n\n```powershell\nyt-dlp --sleep-requests 1 --sleep-interval 2 --max-sleep-interval 5 \"PLAYLIST_URL\"\n```\n\n`--sleep-requests` pauses between metadata requests (extraction); `--sleep-interval`/`--max-sleep-interval` pause a random amount between actual downloads \u2014 important for large batch jobs against sites that rate-limit or flag scraping-like behavior.\n\n### Proxy support\n\n```powershell\nyt-dlp --proxy \"socks5://127.0.0.1:9050\" \"URL\" # SOCKS5, e.g. Tor\nyt-dlp --proxy \"http://127.0.0.1:8080\" \"URL\" # HTTP proxy\n```\n\n### VPN usage\n\nNo special yt-dlp flag needed \u2014 a system-level VPN (WireGuard, OpenVPN client, etc.) simply changes your effective IP for all traffic including yt-dlp. Useful for geo-blocked content (see \u00a719) but subject to the same ToS/legal caveats as \u00a71.\n\n### Custom headers, Referer, User-Agent\n\n```powershell\nyt-dlp --add-header \"Referer:https://example.com\" --user-agent \"Mozilla/5.0 ...\" \"URL\"\n```\n\nOccasionally required for sites that check Referer/User-Agent as a basic anti-hotlinking measure.\n\n### External downloaders / aria2c integration\n\n```powershell\nyt-dlp --downloader aria2c --downloader-args \"aria2c:-x 16 -s 16 -k 1M\" \"URL\"\n```\n\nDelegates the actual byte-fetching to `aria2c` (must be installed separately, e.g. `winget install aria2.aria2` or `scoop install aria2`) for multi-connection, resumable downloading \u2014 can substantially speed up large single-file downloads over a fast connection. **Important**: aria2c support for downloading HLS and DASH formats was removed due to a security vulnerability (CVE-2026-50574, arbitrary code execution via manifest downloads); users affected by this change should migrate to `-N`/`--concurrent-fragments` for concurrent fragment downloads via yt-dlp's native downloader instead \u2014 aria2c remains fine for plain progressive/HTTP downloads, just not HLS/DASH manifests.\n\n---\n\n## 17. Automation (Windows Task Scheduler & Scripts)\n\n*(Advanced)*\n\n### A reusable PowerShell wrapper script\n\nSave as `C:\\yt-dlp\\sync-channels.ps1`:\n\n```powershell\n# sync-channels.ps1 \u2014 run periodically via Task Scheduler\n$ytdlp = \"C:\\yt-dlp\\yt-dlp.exe\"\n$config = \"$env:APPDATA\\yt-dlp\\config.txt\"\n$log = \"C:\\yt-dlp\\logs\\sync-$(Get-Date -Format 'yyyy-MM-dd').log\"\n\nNew-Item -ItemType Directory -Force -Path (Split-Path $log) | Out-Null\n\n# First, self-update\n& $ytdlp -U *>> $log\n\n# Then sync a list of channels/playlists, each using the shared archive file\n$urls = Get-Content \"C:\\yt-dlp\\watchlist.txt\"\nforeach ($url in $urls) {\n & $ytdlp --config-locations $config $url *>> $log\n}\n```\n\n`watchlist.txt` is just one channel/playlist URL per line.\n\n### Registering it in Task Scheduler\n\n```powershell\n$action = New-ScheduledTaskAction -Execute \"powershell.exe\" `\n -Argument \"-NoProfile -ExecutionPolicy Bypass -File `\"C:\\yt-dlp\\sync-channels.ps1`\"\"\n$trigger = New-ScheduledTaskTrigger -Daily -At 3am\n$settings = New-ScheduledTaskSettingsSet -StartWhenAvailable -WakeToRun\nRegister-ScheduledTask -TaskName \"yt-dlp Channel Sync\" -Action $action -Trigger $trigger -Settings $settings\n```\n\nOr via the GUI: **Task Scheduler \u2192 Create Task\u2026 \u2192 Triggers: Daily at 3 AM \u2192 Actions: Start a program \u2192 `powershell.exe` with the argument above \u2192 Conditions: uncheck \"Start the task only if the computer is on AC power\" if this is a laptop.**\n\n### A simple `.bat` alternative (if you prefer not to touch PowerShell scripting)\n\n```bat\n@echo off\ncd /d C:\\yt-dlp\nyt-dlp.exe -U\nyt-dlp.exe --config-locations \"%APPDATA%\\yt-dlp\\config.txt\" \"https://www.youtube.com/@ChannelName/videos\"\n```\n\nDouble-click-able, and schedulable the same way via Task Scheduler pointing directly at the `.bat` file.\n\n### Automatic updates\n\nAdding `yt-dlp -U` as the first line of any scheduled script (as above) keeps yt-dlp current without you having to remember \u2014 important, since YouTube/other sites frequently break older versions within weeks.\n\n### Automatic backups of your archive/config\n\n```powershell\n# Add near the top of sync-channels.ps1\nCopy-Item \"C:\\yt-dlp\\watchlist.txt\" \"C:\\yt-dlp\\backups\\watchlist-$(Get-Date -Format yyyyMMdd).txt\" -Force\nCopy-Item \"$env:APPDATA\\yt-dlp\\config.txt\" \"C:\\yt-dlp\\backups\\config-$(Get-Date -Format yyyyMMdd).txt\" -Force\n```\n\nA `--download-archive` file in particular is worth backing up \u2014 losing it means yt-dlp will happily re-download everything it already has on the next sync.\n\n### Quick shell aliases/functions (PowerShell profile)\n\nAdd to `$PROFILE` (open it with `notepad $PROFILE`, creating the file if it doesn't exist):\n\n```powershell\nfunction ytv { yt-dlp @args }\nfunction yta { yt-dlp -x --audio-format opus --audio-quality 0 @args }\nfunction ytbest { yt-dlp -f \"bv*+ba/b\" -S \"res,vcodec:h264,acodec:aac\" --merge-output-format mkv @args }\n```\n\nReload with `. $PROFILE`, then just run `yta \"URL\"` for a quick audio grab.\n\n---\n\n## 18. Performance Optimization\n\n*(Intermediate/Advanced)*\n\n### Faster downloads\n\n- `--concurrent-fragments 4` (or higher on very fast connections) for DASH/HLS streams \u2014 see \u00a716.\n- Prefer `https` protocol formats over `m3u8`/HLS when both are offered at the same quality (`-S proto` puts this first by default already).\n- Use `aria2c` as an external downloader for large **progressive** (non-DASH) files (\u00a716) \u2014 not for HLS/DASH manifests post-CVE-2026-50574.\n\n### Parallel fragments vs. parallel *videos*\n\nyt-dlp does **not** parallelize multiple separate video downloads within a single invocation by design (it's sequential per URL/playlist item). To run several downloads truly in parallel, launch multiple `yt-dlp` processes (e.g. via separate PowerShell jobs or `Start-Process`) \u2014 but be mindful this multiplies your request rate against the source site and can trigger rate-limiting/IP flags faster.\n\n```powershell\nStart-Job { yt-dlp \"URL1\" }\nStart-Job { yt-dlp \"URL2\" }\nGet-Job | Wait-Job | Receive-Job\n```\n\n### Disk optimization\n\n- Download to an **SSD** when possible \u2014 FFmpeg's merge/remux step is I/O-heavy (reading two streams, writing one), and mechanical HDDs noticeably slow this down on long/high-bitrate videos.\n- If archiving to a slower HDD or **network drive**, download to a local SSD/temp folder first, then move the finished file \u2014 avoids write-stutter mid-download and avoids the network-drive quirks in \u00a720.\n\n### Network optimization\n\n- `--sleep-requests`/`--sleep-interval` (\u00a716) trade raw speed for reliability on large batch jobs \u2014 worth it to avoid mid-batch rate-limit bans.\n- A wired connection (or 5GHz Wi-Fi at minimum) matters more than any yt-dlp flag for 4K/8K downloads.\n\n### CPU usage\n\n- CPU load in yt-dlp itself is minimal \u2014 the heavy lifting (merging/remuxing/re-encoding) is entirely FFmpeg's job.\n- **Remuxing** (`--remux-video`, container-only changes like MP4\u2194MKV with compatible codecs) is fast and low-CPU \u2014 no re-encoding happens.\n- **Re-encoding** (`--recode-video`, or any codec conversion that isn't a simple remux) is CPU-intensive and can take far longer than the download itself on lower-end CPUs \u2014 avoid `--recode-video` unless you specifically need a codec change; prefer `--remux-video` when just changing containers.\n\n### Memory usage\n\nGenerally low (well under 500MB even for 4K/8K downloads) since yt-dlp streams to disk rather than buffering entire files in RAM \u2014 memory usage climbing significantly usually indicates an unrelated issue (e.g. `--write-comments` on a video with an enormous comment section).\n\n---\n\n## 19. Troubleshooting\n\n*(All levels)*\n\n```mermaid\nflowchart TD\n Start[yt-dlp command failed] --> Q1{What kind of error?}\n Q1 -->|HTTP error code| HTTP[See HTTP error table]\n Q1 -->|\"command not found\"| PATH[PATH issue \u2014 see \u00a719 PATH section]\n Q1 -->|FFmpeg-related| FF[See \u00a73 FFmpeg troubleshooting]\n Q1 -->|Filename / path error| FN[Check Unicode / long-path \u2014 see \u00a720]\n Q1 -->|Login/cookie error| CK[Re-export cookies \u2014 see \u00a79]\n Q1 -->|Extraction / signature error| SIG[Update yt-dlp: yt-dlp -U]\n HTTP --> Fixed{Fixed?}\n PATH --> Fixed\n FF --> Fixed\n FN --> Fixed\n CK --> Fixed\n SIG --> Fixed\n Fixed -->|No| Issue[Search/open a GitHub issue with -vU log]\n Fixed -->|Yes| Done[Done]\n```\n\n### HTTP and extraction errors\n\n| Error | Cause | Diagnosis | Solution | Prevention |\n|---|---|---|---|---|\n| **HTTP 403 Forbidden** | Expired signature/token, missing cookies, or a site-side block | Run with `-v` and check whether it happens on extraction or on the actual byte download | Update yt-dlp (`-U`), retry, or add `--cookies-from-browser` if the content requires login | Keep yt-dlp updated; don't hammer the same video repeatedly |\n| **HTTP 429 Too Many Requests** | Rate-limited by the source site | Repeats across many URLs in a batch job | Add `--sleep-requests`/`--sleep-interval`, reduce `--concurrent-fragments`, wait before retrying | Use sleep intervals proactively on large batch jobs (\u00a716) |\n| **Signature extraction failed / unable to extract player JS** | Site changed its player/obfuscation; your yt-dlp version is behind | `yt-dlp --version` vs. latest release | `yt-dlp -U`, or reinstall via your package manager if `-U` isn't available for your install method | Update regularly; subscribe to release notifications |\n| **Unsupported URL** | Site not supported, or URL format changed | `yt-dlp --list-extractors \\| Select-String \"sitename\"` | Check if a newer yt-dlp version added support; file/search a GitHub issue | N/A |\n| **SSL / certificate errors** | Outdated CA bundle, corporate proxy MITM, or system clock skew | Try `--no-check-certificates` **temporarily** to confirm it's cert-related (do not leave this on permanently) | Update `certifi` (`pip install -U certifi` for pip installs), fix system clock, or configure corporate proxy cert properly | Keep Windows date/time synced; keep pip installs' dependencies updated |\n| **Geo-blocking** | Content restricted to certain countries | Error message explicitly mentions region restriction | Use `--proxy` or a VPN with an allowed-region exit node (subject to \u00a71's legal caveats) | N/A |\n| **Login failures with `--cookies-from-browser`** | Browser locked the cookie DB, or session expired | Close the browser fully before running; check cookies still work by browsing the site logged in | Close browser first, or export to `cookies.txt` instead (\u00a79) | Re-check cookies periodically for long-running scheduled jobs |\n| **Cookie decryption failures on Windows specifically** | Chromium's DPAPI-encrypted cookie store, run under a different Windows user/session than the browser | Confirm the script/Task Scheduler task runs as *your* Windows user, not `SYSTEM` | Set the scheduled task to run as your own user account, not SYSTEM | Configure Task Scheduler tasks with \"Run only when user is logged on\" if cookies are needed |\n\n### Windows filesystem-specific errors\n\n| Error | Cause | Diagnosis | Solution | Prevention |\n|---|---|---|---|---|\n| **FFmpeg missing / merge not happening** | See \u00a73 fully | `ffmpeg -version` in the same terminal | Install FFmpeg, set `--ffmpeg-location` | Keep FFmpeg on PATH or bundled with yt-dlp |\n| **`'yt-dlp' is not recognized as an internal or external command`** | Not on PATH, or PATH change not applied to current terminal | `where yt-dlp` (CMD) or `Get-Command yt-dlp` (PowerShell) | Re-check PATH entry (\u00a72), restart terminal, or use the full path to the `.exe` | Use winget/scoop/choco, which manage PATH automatically |\n| **Unicode filename errors (rare, mostly cosmetic)** | Legacy CMD code page | Title displays as `?????` in the terminal but the file itself is fine | Ignore, or `chcp 65001` first, or use PowerShell/Windows Terminal | Use Windows Terminal by default |\n| **Long path / \"path too long\" / \"cannot create file\"** | Output template + folder path exceeds 260 characters and long-path support isn't enabled | Try a much shorter `-o` template as a test | Enable Windows long-path support (\u00a720), or shorten the output template | Keep `-o` templates reasonably short; avoid deep nested folders |\n| **Permission denied** | Output folder in a protected location (`Program Files`, `C:\\`, OneDrive-synced folder mid-sync) | Try downloading to `%USERPROFILE%\\Downloads` as a test | Change `-P` to a folder you own, or run terminal as your normal user (not needed/recommended to run as admin) | Never install/download into `Program Files`; keep downloads in your user profile |\n| **Proxy failures** | Misconfigured `--proxy`, or corporate proxy requiring authentication yt-dlp doesn't support out of the box | Test the proxy independently (e.g. via `curl` or a browser) | Fix proxy URL/credentials format: `http://user:pass@host:port` | N/A |\n\n---\n\n## 20. Windows-Specific Tips\n\n*(Intermediate/Advanced)*\n\n### Long path support\n\nClassic Windows limits full paths to 260 characters. To lift this:\n\n1. **Group Policy** (Pro/Enterprise): `gpedit.msc` \u2192 Computer Configuration \u2192 Administrative Templates \u2192 System \u2192 Filesystem \u2192 **Enable Win32 long paths**.\n2. **Registry** (Home edition, or scripted):\n ```powershell\n New-ItemProperty -Path \"HKLM:\\SYSTEM\\CurrentControlSet\\Control\\FileSystem\" `\n -Name \"LongPathsEnabled\" -Value 1 -PropertyType DWORD -Force\n ```\n Reboot after applying.\n3. Even with long paths enabled at the OS level, **some individual applications** (older archivers, some antivirus scanners) may still choke on very long paths \u2014 keeping `-o` templates reasonably short remains good practice regardless.\n\n### NTFS limitations\n\n- Forbidden characters: `\\ / : * ? \" < > |` \u2014 yt-dlp sanitizes these automatically in filenames.\n- Reserved names (`CON`, `PRN`, `AUX`, `NUL`, `COM1`-`COM9`, `LPT1`-`LPT9`) can't be used as filenames \u2014 extremely rare to hit accidentally with video titles, but theoretically possible.\n- Trailing dots and spaces in filenames are silently stripped by Windows \u2014 yt-dlp accounts for this already.\n\n### File permissions\n\nStandard NTFS permissions apply normally; no yt-dlp-specific quirks here beyond the \"don't download into `Program Files`/system folders\" advice in \u00a719.\n\n### SmartScreen\n\nWindows SmartScreen may flag a freshly downloaded `yt-dlp.exe` as \"unrecognized app\" the first time you run it, since it's an unsigned/less-common binary with no install-base reputation yet. Click **\"More info\" \u2192 \"Run anyway\"** after verifying the checksum (\u00a72) \u2014 this is expected for many legitimate open-source CLI tools and not a sign of malware, *provided* you downloaded it from the official `github.com/yt-dlp/yt-dlp` releases page and verified the hash.\n\n### Windows Defender false positives\n\nSome antivirus engines occasionally flag `yt-dlp.exe` (a PyInstaller-bundled Python executable) as a false positive, because generic \"PyInstaller-packed binary\" heuristics are a common pattern abused by actual malware too. If Defender quarantines it:\n\n1. Re-verify the SHA256 checksum against the official release (\u00a72) \u2014 never \"just allow\" a file you haven't checked.\n2. If it checks out, add an exclusion for the specific file/folder in **Windows Security \u2192 Virus & threat protection \u2192 Manage settings \u2192 Add or remove exclusions**.\n3. If you're uneasy trusting the compiled `.exe`, use the `pip install yt-dlp` route instead \u2014 it's the same source code without a pre-built binary to worry about.\n\n### Portable installations\n\nKeep `yt-dlp.exe`, `ffmpeg.exe`, `ffprobe.exe`, and a `yt-dlp.conf` all together in one folder (\u00a72/\u00a73) for a fully self-contained, USB-drive-portable setup with zero registry/PATH dependency on the host machine \u2014 just double-check the portable config's paths (`-P`, `--download-archive`) use relative or environment-variable-based paths rather than hardcoded drive letters, since USB drive letters can change between PCs.\n\n### OneDrive interaction\n\nIf your Downloads/Videos folder is OneDrive-synced (default on many Windows 11 setups):\n\n- Large video files can trigger OneDrive to start uploading mid-download, competing for disk I/O and occasionally locking the file briefly \u2014 this can cause intermittent \"file in use\" errors during FFmpeg's merge step.\n- **Recommendation**: point `-P` at a non-synced local folder (e.g. `C:\\Downloads\\yt-dlp` or `D:\\Media`) instead, and manually move finished files into OneDrive afterward if you want them backed up.\n- If files are set to **\"Files On-Demand\"** (cloud-only placeholder), make sure the destination folder itself is fully local \u2014 writing directly into a cloud-only-placeholder folder works but adds sync overhead during active downloads.\n\n### Network drives\n\n- Downloading directly to a network share (`\\\\NAS\\Videos` or a mapped drive letter) works, but is meaningfully slower for the FFmpeg merge step (lots of read+write over the network for what's normally a fast local operation).\n- **Recommendation**: download to a local temp folder, then move (`Move-Item`) the finished file to the network location \u2014 much faster overall and avoids partial-write corruption if the network connection blips mid-download.\n- Mapped drive letters (`Z:\\`) inside scheduled tasks can be unreliable if the task runs before the drive is remapped (e.g. right after boot) \u2014 prefer full UNC paths (`\\\\NAS\\Videos\\...`) in automation scripts instead of a drive letter.\n\n---\n\n## 21. Best Practices\n\n*(All levels)*\n\n### Folder organization\n\n- One root folder per \"library\" (e.g. `D:\\Media\\YouTube\\`), with subfolders by uploader/channel via `-o` templates (\u00a78) \u2014 avoid one giant flat folder with thousands of files.\n- Keep audio-only and video downloads in separate root folders if you use both regularly \u2014 different naming conventions (artist/album vs. uploader/title) don't mix well in one tree.\n\n### Naming conventions\n\n- Always include `%(id)s` somewhere in your output template \u2014 video IDs are unique and prevent silent overwrites when two videos happen to share a title.\n- Decide once whether you want Unicode titles as-is or `--restrict-filenames` (ASCII-safe) \u2014 mixing the two across different runs makes an archive inconsistent and harder to search/sort later.\n\n### Backups\n\n- Back up your **`--download-archive`** file and **config file(s)** regularly (\u00a717) \u2014 losing the archive means re-downloading everything on the next sync.\n- The downloaded media itself is regenerable (re-run yt-dlp) as long as the source is still online; the archive/config are the only truly \"irreplaceable\" small files in this workflow.\n\n### Config management\n\n- Keep one well-commented base config (\u00a77) rather than retyping flags per command.\n- Use `--config-locations` profile files (\u00a77) for task-specific overrides (audio-only profile, archival/lossless profile, etc.) instead of one giant config with conflicting settings.\n\n### Updates\n\n- Update yt-dlp **before** any significant batch job \u2014 site extractors break often, and a stale version is the #1 cause of \"it randomly stopped working\" reports.\n- Automate the update as the first line of any scheduled script (\u00a717).\n\n### Security\n\n- Only download the `.exe` from the official `github.com/yt-dlp/yt-dlp` releases page (\u00a72); verify checksums.\n- Never share `cookies.txt` or a browser profile that has active login sessions.\n- Be cautious with random third-party \"yt-dlp GUI\" wrappers (\u00a724) \u2014 stick to actively maintained, source-available ones.\n\n### Privacy\n\n- `--cookies-from-browser` reads live session cookies \u2014 treat any exported `cookies.txt` file as sensitive as a password.\n- `--write-comments`/`--write-info-json` can capture other users' comment text/usernames \u2014 be mindful if you're archiving content for sharing elsewhere.\n\n### Responsible downloading\n\n- Respect `--sleep-interval`/rate limits on batch jobs rather than hammering a site as fast as technically possible (\u00a716, \u00a718) \u2014 this is both good etiquette and reduces your own odds of getting rate-limited or blocked.\n- Revisit \u00a71's legal/ToS considerations for anything beyond personal, fair-use archival of content you have rights to.\n\n---\n\n## 22. Frequently Used Commands (Cheat Sheet)\n\n| Goal | Command |\n|---|---|\n| Best quality video (any resolution) | `yt-dlp -f \"bv*+ba/b\" \"URL\"` |\n| Best quality, capped at 1080p, MKV | `yt-dlp -S \"res:1080,vcodec:h264,acodec:aac\" --merge-output-format mkv --remux-video mkv \"URL\"` |\n| Best quality, capped at 4K | `yt-dlp -f \"bv*[height<=2160]+ba/b[height<=2160]\" \"URL\"` |\n| Best quality audio, no re-encode overhead | `yt-dlp -x --audio-format opus --audio-quality 0 \"URL\"` |\n| Best quality audio, universal compatibility | `yt-dlp -x --audio-format mp3 --audio-quality 0 \"URL\"` |\n| Download an entire playlist | `yt-dlp \"PLAYLIST_URL\"` |\n| Download a whole channel | `yt-dlp \"https://www.youtube.com/@Channel/videos\"` |\n| Convert audio (any downloaded video \u2192 MP3) | `yt-dlp -x --audio-format mp3 \"URL\"` |\n| Embed thumbnail as cover art | `yt-dlp --embed-thumbnail \"URL\"` |\n| Download subtitles (manual, English) | `yt-dlp --write-subs --sub-langs en \"URL\"` |\n| Embed metadata + chapters | `yt-dlp --embed-metadata --embed-chapters \"URL\"` |\n| Use browser cookies | `yt-dlp --cookies-from-browser chrome \"URL\"` |\n| Mark SponsorBlock segments (non-destructive) | `yt-dlp --sponsorblock-mark all \"URL\"` |\n| Remove SponsorBlock segments (destructive) | `yt-dlp --sponsorblock-remove sponsor,selfpromo \"URL\"` |\n| Use a SOCKS5/HTTP proxy | `yt-dlp --proxy \"socks5://127.0.0.1:9050\" \"URL\"` |\n| Sync a channel, skip already-downloaded | `yt-dlp --download-archive archive.txt \"CHANNEL_URL\"` |\n| Custom output template | `yt-dlp -o \"%(uploader)s/%(title)s [%(id)s].%(ext)s\" \"URL\"` |\n| List available formats first | `yt-dlp -F \"URL\"` |\n| Update yt-dlp (standalone `.exe` only) | `yt-dlp -U` |\n\n---\n\n## 23. Version Differences\n\n### yt-dlp vs. youtube-dl\n\nyt-dlp is a youtube-dl fork based on the now-inactive youtube-dlc, focused on adding new features/patches while staying current with upstream youtube-dl. Practical differences that matter day-to-day:\n\n- **Format sorting**: yt-dlp changed the default sort so higher resolution/better codecs are preferred over raw bitrate, and added the `-S` flag for full custom control \u2014 youtube-dl's format selection is comparatively primitive.\n- **SponsorBlock** (\u00a715): yt-dlp-exclusive.\n- Release cadence: yt-dlp ships fixes within days of a site breaking; youtube-dl's development has been comparatively dormant.\n- **`--ignore-errors` is enabled by default** in yt-dlp (youtube-dl requires the flag explicitly) \u2014 use `--abort-on-error` or `--compat-options abort-on-error` to restore the old fail-fast behavior.\n- **Multi-stream merging behavior differs**: yt-dlp does not allow merging multiple audio/video streams into one file by default the way youtube-dlc did (since it conflicts with `-f bv*+ba`); use `--audio-multistreams`/`--video-multistreams`, or `--compat-options multistreams`, to re-enable it.\n- **Playlist metadata files**: yt-dlp writes the same thumbnail/description/infojson metadata for playlists as for individual videos by default; use `--no-write-playlist-metafiles` or `--compat-options no-playlist-metafiles` to revert to youtube-dl's behavior.\n- For full backward compatibility with youtube-dl's exact defaults across the board: `--compat-options all`.\n\n### Deprecated options & modern replacements\n\n| Deprecated / legacy | Modern replacement |\n|---|---|\n| `--write-annotations` (site no longer supports it) | n/a \u2014 removed, YouTube annotations don't exist anymore |\n| Manually specifying `--external-downloader aria2c` for HLS/DASH | Use `-N`/`--concurrent-fragments` \u2014 aria2c HLS/DASH support was removed for security reasons (CVE-2026-50574) |\n| Old `%()s`-style unsafe conversions in `--exec` | Use `%()q` \u2014 unsafe `%()s`-style conversions were restricted for security; numeric conversions are unaffected |\n| `youtube-dl`-style single quoting on Windows examples | Use double quotes on Windows \u2014 single quotes don't reliably work the same way in cmd.exe/PowerShell as on Unix shells |\n\n### Breaking / notable recent changes (as of mid-2026)\n\n- The minimum recommended Python version was raised to 3.11, since Python 3.10 reaches end-of-life in October 2026 \u2014 pip-install users on old Python should upgrade Python itself soon.\n- Official Windows release binaries will soon require Windows 10 or later (i.e., Windows 7/8.1 standalone `.exe` support is being phased out \u2014 irrelevant if you're already on Windows 10/11, as this guide assumes).\n- Aria2c HLS/DASH support removed (security fix) \u2014 see above.\n- `--write-link`-derived shortcut file output is now validated/sanitized against a command-injection vulnerability (CVE-2026-55404) \u2014 always keep yt-dlp updated rather than pinning an old version for \"stability.\"\n\n---\n\n## 24. GUI Alternatives\n\n*(For users who'd rather not use the command line at all)*\n\n| GUI | Platform | Status | Notes |\n|---|---|---|---|\n| **yt-dlg** | Windows/macOS/Linux | Community-maintained fork of the old `youtube-dl-gui` | Simple, lightweight, wraps yt-dlp directly; good for absolute beginners who just want point-and-click downloads |\n| **Stacher** | Windows/macOS/Linux | Actively maintained, Electron-based | Clean modern UI, queue management, format selection dropdowns; heavier resource footprint than a native app |\n| **Media Downloader (GPL)** | Windows/Linux (Flatpak on Linux) | Actively maintained | GTK-based, exposes most yt-dlp flags through checkboxes, good for users who want GUI *and* fine control |\n| **Parabolic** (formerly \"Video Downloader\") | Windows/Linux (also available via Microsoft Store on Windows) | Actively maintained | Modern Fluent-style UI on Windows, good playlist/batch support |\n\n**Comparison notes:**\n- All of the above are **wrappers around yt-dlp itself** \u2014 they don't reimplement extraction logic, so their reliability directly depends on how quickly they bundle yt-dlp updates. If a GUI stops working, check whether its *bundled* yt-dlp is outdated before assuming the tool is abandoned.\n- None of them expose 100% of yt-dlp's CLI surface (advanced `-S` sort strings, SponsorBlock category granularity, etc.) \u2014 power users doing anything beyond \"download this video/playlist at this quality\" will eventually hit the GUI's ceiling and need the CLI anyway.\n- **Recommended use case split**: GUI for occasional single-video downloads by non-technical users; CLI (this guide) for anything involving automation, batch jobs, precise format control, or SponsorBlock/subtitle/metadata customization.\n\nAlways verify current maintenance status before installing any of these \u2014 GUI wrapper projects come and go faster than yt-dlp itself; check the project's GitHub for recent commits before trusting it with your setup.\n\n---\n\n## 25. Appendix\n\n### Glossary\n\n| Term | Meaning |\n|---|---|\n| **Extractor** | The site-specific module yt-dlp uses to parse a given website and find downloadable media |\n| **DASH** | Dynamic Adaptive Streaming over HTTP \u2014 the technology behind separate video/audio streams on YouTube etc. |\n| **HLS** | HTTP Live Streaming \u2014 Apple's segmented streaming protocol, common for live streams |\n| **Remux** | Changing a file's container (e.g. MP4 \u2192 MKV) without re-encoding the actual video/audio data \u2014 fast, lossless |\n| **Recode/Transcode** | Actually re-encoding video/audio into a different codec \u2014 slow, and always introduces some quality loss (lossy re-encode) |\n| **Format sort (`-S`)** | yt-dlp's preference-ranking system for choosing among multiple available formats |\n| **Format selector (`-f`)** | The expression language for filtering/choosing specific formats |\n| **PO Token** | A YouTube anti-bot proof-of-origin token some clients require for certain streams \u2014 handled automatically by yt-dlp's JS-challenge solving when needed |\n\n### Common command reference (quick recall)\n\n```\n-F list formats\n-f SELECTOR choose format(s)\n-S SORT_STRING custom sort order\n-o TEMPLATE output filename template\n-P PATH output folder\n-x extract audio\n--audio-format FORMAT audio codec for -x\n--embed-metadata/-thumbnail/-chapters/-subs\n--sponsorblock-mark/-remove CATEGORIES\n--cookies-from-browser BROWSER\n--download-archive FILE\n--playlist-items RANGE\n-U self-update (standalone exe only)\n-v verbose (debugging)\n```\n\n### Useful links\n\n- Official repository: https://github.com/yt-dlp/yt-dlp\n- Official releases: https://github.com/yt-dlp/yt-dlp/releases\n- Official wiki: https://github.com/yt-dlp/yt-dlp/wiki\n- Official FFmpeg Windows builds: https://github.com/yt-dlp/FFmpeg-Builds\n- FFmpeg project documentation: https://ffmpeg.org/documentation.html\n- SponsorBlock project: https://sponsor.ajay.app/\n- yt-dlp Wiki \u2014 Installation: https://github.com/yt-dlp/yt-dlp/wiki/Installation\n\n### Trusted community resources\n\n- GitHub Issues (`yt-dlp/yt-dlp/issues`) \u2014 the best place to check for currently-known, actively-tracked bugs before assuming your own setup is broken.\n- `r/DataHoarder` and `r/youtubedl` on Reddit \u2014 active communities for archival/automation workflows.\n- Official Discord (linked from the GitHub repo) \u2014 real-time help from maintainers and power users.\n\n---\n\n*This guide reflects yt-dlp `2026.07.04` and the state of the official documentation as of July 2026. yt-dlp updates frequently \u2014 run `yt-dlp --help` and check the release notes at the link above for anything that may have changed since.*\n", "creation_timestamp": "2026-07-14T08:07:20.031625Z"} {"uuid": "3d2fd8e2-1d31-418a-9117-81b5a3a37f36", "vulnerability_lookup_origin": "1a89b78e-f703-45f3-bb86-59eb712668bd", "author": "9f56dd64-161d-43a6-b9c3-555944290a09", "vulnerability": "CVE-2026-55404", "type": "seen", "source": "https://gist.github.com/akib-h/a603a4aaf4aab24ac683c30e9a2ad670", "content": "# The Ultimate yt-dlp Guide for Windows (10 & 11)\n\n> Researched against the official [yt-dlp GitHub repo](https://github.com/yt-dlp/yt-dlp), the [yt-dlp Wiki](https://github.com/yt-dlp/yt-dlp/wiki), and community sources, current as of **July 2026** (latest stable release: `2026.07.04`). yt-dlp updates constantly \u2014 always trust `yt-dlp --help` and `yt-dlp -U` over any guide, including this one.\n\n---\n\n## \ud83d\udccc TL;DR \u2014 Just Get It Working\n\nFor people who want the short version: this is the exact setup used throughout the rest of this guide (**MKV container, 1080p cap, best audio, with an easy way to grab the untouched original quality**).\n\n```powershell\n# 1. Install with winget (opens PowerShell as your normal user)\nwinget install yt-dlp.yt-dlp\nwinget install Gyan.FFmpeg\n\n# 2. Make a config folder + file\nmkdir \"$env:APPDATA\\yt-dlp\" -Force\nnotepad \"$env:APPDATA\\yt-dlp\\config.txt\"\n```\n\nPaste this into the config file, save, close:\n\n```ini\n# %APPDATA%\\yt-dlp\\config.txt\n# Prefer MKV, cap at 1080p, take the best audio available\n-S \"res:1080,vcodec:h264,acodec:aac\"\n--merge-output-format mkv\n--remux-video mkv\n-o \"%(uploader)s/%(title)s [%(id)s].%(ext)s\"\n-P \"~/Videos/yt-dlp\"\n--embed-thumbnail\n--embed-metadata\n--embed-chapters\n--download-archive \"%(home)s/yt-dlp-archive.txt\"\n--no-mtime\n```\n\nThen it's just:\n\n```powershell\n# Best up to 1080p, muxed into MKV automatically (uses the config above)\nyt-dlp \"https://www.youtube.com/watch?v=XXXXXXXXXXX\"\n\n# Grab the ORIGINAL/highest-available quality instead (ignores the 1080p cap for this run)\nyt-dlp -f \"bv*+ba/b\" -S \"res,vcodec:h264,acodec:aac\" --merge-output-format mkv \"URL\"\n\n# Audio only, best quality, as Opus\nyt-dlp -x --audio-format opus --audio-quality 0 \"URL\"\n```\n\nThat's the whole guide in three commands. Everything below explains *why* they work, what else exists, and how to fix it when it breaks. Jump to [\u00a722 Cheat Sheet](#22-frequently-used-commands-cheat-sheet) any time you just need a command.\n\n---\n\n## Table of Contents\n\n1. [Introduction](#1-introduction)\n2. [Installation](#2-installation)\n3. [FFmpeg](#3-ffmpeg)\n4. [Windows Terminal Basics](#4-windows-terminal-cmd-vs-powershell-vs-windows-terminal)\n5. [Basic Usage](#5-basic-usage)\n6. [Format Selection](#6-format-selection)\n7. [Configuration Files](#7-configuration-files)\n8. [Output Templates](#8-output-templates)\n9. [Authentication & Cookies](#9-authentication)\n10. [Batch Downloads](#10-batch-downloads)\n11. [Playlists](#11-playlists)\n12. [Audio Downloads](#12-audio-downloads)\n13. [Subtitles](#13-subtitle-downloads)\n14. [Metadata](#14-metadata)\n15. [SponsorBlock](#15-sponsorblock)\n16. [Advanced Features](#16-advanced-features)\n17. [Automation](#17-automation-windows-task-scheduler--scripts)\n18. [Performance Optimization](#18-performance-optimization)\n19. [Troubleshooting](#19-troubleshooting)\n20. [Windows-Specific Tips](#20-windows-specific-tips)\n21. [Best Practices](#21-best-practices)\n22. [Cheat Sheet](#22-frequently-used-commands-cheat-sheet)\n23. [Version Differences (youtube-dl vs yt-dlp)](#23-version-differences)\n24. [GUI Alternatives](#24-gui-alternatives)\n25. [Appendix](#25-appendix)\n\n---\n\n## 1. Introduction\n\n### What yt-dlp is\n\nyt-dlp is a free, open-source, command-line media downloader for Windows, macOS, Linux, BSD and Android. It's a fork of `youtube-dl` (via the intermediate `youtube-dlc` fork), maintained by an active community that ships releases roughly every one to two weeks. It's written in Python, distributed as both a standalone Windows `.exe` and a `pip` package, and can extract audio/video from thousands of sites beyond YouTube.\n\n### Why yt-dlp over youtube-dl\n\nyt-dlp's main focus is adding new features and patches while keeping up to date with the original youtube-dl project. Concretely, that means:\n\n- **Format sorting (`-S`)**: the default format-sorting behavior changed so higher resolution and better codecs are preferred over simply picking the largest bitrate, and `-S` lets you fully customize the sort order \u2014 this is the backbone of the MKV/1080p setup in the TL;DR above.\n- **SponsorBlock integration**: mark or remove sponsor segments in YouTube videos using the SponsorBlock API \u2014 no browser extension required.\n- Much faster development cadence \u2014 youtube-dl extractors frequently break when sites change; yt-dlp patches these far more quickly.\n- JS-challenge solving, PO tokens, and other modern anti-bot workarounds that youtube-dl does not implement.\n\n### Supported websites\n\nOfficially \"thousands,\" ranging from YouTube, Twitch, Vimeo, SoundCloud, TikTok, Twitter/X, Reddit, Bilibili, and Niconico to countless news sites, educational platforms, and live-streaming services. The canonical, always-current list lives at `yt-dlp --list-extractors` or `supportedsites.md` in the repo \u2014 do **not** trust any third-party \"supported sites\" list, since they go stale within weeks.\n\n### Key features\n\n- Merges separate video/audio streams via FFmpeg (needed because YouTube etc. deliver video and audio as separate DASH streams above 720p/\"pre-merged\" quality)\n- Playlist and channel downloading with item ranges\n- Subtitle download/embedding (manual and auto-generated)\n- Metadata, chapters, thumbnail embedding\n- Cookie import directly from browsers (no manual export needed)\n- Live-stream recording, including \"from the start\"\n- Format filtering/sorting language for very precise quality control\n- Plugin system for extending extractors and post-processors\n- Aria2c / external downloader integration for faster or resumable transfers\n\n### Legal and ethical considerations\n\nyt-dlp itself is legal open-source software. Whether downloading a specific piece of content is legal depends on **copyright law and the target platform's Terms of Service** in your jurisdiction \u2014 most streaming platforms' ToS prohibit downloading content you don't have explicit rights to. This guide does not provide legal advice; use yt-dlp for content you own, that is licensed under permissive terms (Creative Commons, public domain), or that you otherwise have the right to download (e.g., your own uploads, or explicit \"download\" permission from the creator).\n\n### Limitations\n\n- Cannot download DRM-protected streams (most paid streaming services \u2014 Netflix, Disney+, Spotify, etc. \u2014 are explicitly out of scope and unsupported by design).\n- Site extractors break whenever a platform changes its internals; you rely on the community shipping a fix, usually within days.\n- Livestream/DASH edge cases, geo-restrictions, and login walls can require extra configuration (cookies, proxies) covered in \u00a79 and \u00a716.\n- No official GUI \u2014 it's a CLI-first tool (see \u00a724 for third-party GUIs).\n\n---\n\n## 2. Installation\n\n```mermaid\nflowchart TD\n A[Choose install method] --> B{Do you want automaticupdates & PATH setup?}\n B -->|Yes, easiest| C[winget install yt-dlp.yt-dlp]\n B -->|Yes, I already use Scoop| D[scoop install yt-dlp]\n B -->|Yes, I already use Chocolatey| E[choco install yt-dlp]\n B -->|No, I want full control| F[Download yt-dlp.exe manually]\n B -->|I want the Python package /plugin ecosystem| G[pip install yt-dlp]\n F --> H[Place in a folder, e.g. C:\\yt-dlp]\n H --> I[Add folder to PATH]\n C --> J[Install FFmpeg]\n D --> J\n E --> J\n I --> J\n G --> J\n J --> K[Verify: yt-dlp -v --version]\n```\n\n### Standalone Binary (Recommended for most people)\n\nThis is the officially recommended method \u2014 a single `.exe`, no Python required.\n\n1. Go to the official releases page: **https://github.com/yt-dlp/yt-dlp/releases/latest**\n2. Under **Assets**, download `yt-dlp.exe` (the plain Windows build). There are also `yt-dlp_x86.exe` (32-bit) and `yt-dlp_win_arm64.exe` builds for niche systems.\n3. **Verifying authenticity**: yt-dlp release assets are signed. Each release includes a `SHA2-256SUMS` file and, for recent releases, GPG signatures (`SHA2-256SUMS.sig`) signed with the maintainers' keys published in the repo (`public.key`). To verify on Windows PowerShell:\n ```powershell\n Get-FileHash .\\yt-dlp.exe -Algorithm SHA256\n # Compare the output hash against the value in SHA2-256SUMS from the same release\n ```\n4. **Portable installation / folder structure**: create a dedicated folder, e.g. `C:\\yt-dlp\\`, and keep `yt-dlp.exe`, `ffmpeg.exe`, `ffprobe.exe`, and an optional `yt-dlp.conf` all in that same folder. This is the cleanest, fully portable setup \u2014 nothing touches the registry, and you can copy the whole folder to another PC.\n ```\n C:\\yt-dlp\\\n \u251c\u2500\u2500 yt-dlp.exe\n \u251c\u2500\u2500 ffmpeg.exe\n \u251c\u2500\u2500 ffprobe.exe\n \u2514\u2500\u2500 yt-dlp.conf (optional, see \u00a77)\n ```\n5. **Adding to PATH** (so you can run `yt-dlp` from any folder/terminal):\n - Press **Start**, search **\"Edit the system environment variables\"** \u2192 **Environment Variables\u2026**\n - Under **User variables**, select **Path** \u2192 **Edit** \u2192 **New** \u2192 paste `C:\\yt-dlp` \u2192 **OK** on every dialog.\n - Restart any open terminal windows (PATH changes don't apply to already-open sessions).\n6. **Updating**: `yt-dlp -U` self-updates the binary in place by downloading the newest release and replacing itself. This only works for the **standalone binary**, not for pip/winget/scoop/choco installs.\n - **When it doesn't work**: if `-U` fails with a permissions error, it's usually because the `.exe` lives in a protected folder (e.g. `Program Files`) without write access \u2014 move it to a user-writable folder like `C:\\yt-dlp` or your user profile. If it fails silently behind a corporate proxy/firewall, download the new release manually instead.\n\n### Winget\n\nWinget is Microsoft's official package manager, built into Windows 10 (1809+) and all Windows 11 versions.\n\n```powershell\n# Install\nwinget install yt-dlp.yt-dlp\n\n# Upgrade\nwinget upgrade yt-dlp.yt-dlp\n\n# Uninstall\nwinget uninstall yt-dlp.yt-dlp\n```\n\nThis is also documented directly on the official yt-dlp Installation wiki page as `winget install yt-dlp`, updated with `winget upgrade yt-dlp`. Winget automatically places the executable on PATH, so no manual PATH editing is required.\n\n### Scoop\n\nScoop installs command-line tools into your user profile without needing admin rights.\n\n```powershell\n# One-time: install Scoop itself, if you don't have it\nirm get.scoop.sh | iex\n\n# Install yt-dlp\nscoop install yt-dlp\n\n# Update (just yt-dlp)\nscoop update yt-dlp\n\n# Update everything Scoop manages\nscoop update *\n\n# Uninstall\nscoop uninstall yt-dlp\n```\n\nThe command is confirmed directly by the official wiki (`scoop update yt-dlp`).\n\n### Chocolatey\n\nChocolatey requires an elevated (administrator) PowerShell.\n\n```powershell\n# Install (run PowerShell as Administrator first)\nchoco install yt-dlp\n\n# Upgrade\nchoco upgrade yt-dlp\n\n# Uninstall\nchoco uninstall yt-dlp\n```\n\nConfirmed by the official wiki as `choco install yt-dlp`, with updates via `choco upgrade yt-dlp`. Note that the community Chocolatey package is third-party maintained (not published by the yt-dlp team directly), so it can lag a release or two behind \u2014 check the version before relying on brand-new features.\n\n### Python (pip)\n\nBest if you want the plugin ecosystem, want to pin a specific Python version, or are integrating yt-dlp into your own scripts as a library.\n\n1. **Install Python**: get the latest Python 3 from **python.org** (check **\"Add python.exe to PATH\"** during setup). As of the 2026.06.09 release, the minimum supported Python versions for related tooling were raised, and yt-dlp itself now recommends Python 3.11 or newer, since Python 3.10 reaches end-of-life in October 2026.\n2. **Install yt-dlp**:\n ```powershell\n py -m pip install -U \"yt-dlp[default]\"\n ```\n The `[default]` extra pulls in recommended optional dependencies (`mutagen`, `pycryptodomex`, `websockets`, `brotli`, `certifi`, etc.) for full feature support.\n3. **Updating**:\n ```powershell\n py -m pip install -U \"yt-dlp[default]\"\n ```\n4. **Virtual environments** (recommended if you also do Python development and don't want dependency conflicts):\n ```powershell\n py -m venv $env:USERPROFILE\\.venvs\\ytdlp\n & \"$env:USERPROFILE\\.venvs\\ytdlp\\Scripts\\Activate.ps1\"\n pip install -U \"yt-dlp[default]\"\n ```\n To run it without activating every time, call the venv's yt-dlp directly: `& \"$env:USERPROFILE\\.venvs\\ytdlp\\Scripts\\yt-dlp.exe\" URL`, or add an alias (see \u00a717).\n\n**Advantages vs. standalone `.exe`**: easy access to nightly/master builds (`pip install --pre -U yt-dlp` for prerelease builds, or install straight from the `master` branch tarball), simpler scripting/library use, easier plugin installs.\n\n**Disadvantages**: extra dependency (Python itself) to maintain and keep patched; slightly slower startup time than the compiled binary; more moving parts to break (venv path issues, PATH shadowing between multiple Python installs).\n\n### Summary comparison table\n\n| Method | Admin rights? | Auto PATH setup | Self-update command | Best for |\n|---|---|---|---|---|\n| Standalone `.exe` | No | Manual | `yt-dlp -U` | Full control, portable USB installs |\n| winget | No (user scope) | Yes | `winget upgrade yt-dlp.yt-dlp` | Most Windows 10/11 users |\n| Scoop | No | Yes | `scoop update yt-dlp` | Power users who like Scoop's ecosystem |\n| Chocolatey | Yes | Yes | `choco upgrade yt-dlp` | Admin-managed / enterprise machines |\n| pip | No | Yes (via Python Scripts dir) | `pip install -U yt-dlp[default]` | Scripting, plugins, nightly builds |\n\n---\n\n## 3. FFmpeg\n\n### Why FFmpeg is required\n\nYouTube (and many other sites) deliver anything above roughly 1080p \u2014 and often 1080p itself for the highest-efficiency codecs \u2014 as **separate** video-only and audio-only streams (DASH). YouTube streams 4K/8K as separate video and audio tracks, and FFmpeg is what merges them back together into one playable file. FFmpeg is also required for: audio extraction/re-encoding (MP3, FLAC, Opus, etc.), embedding thumbnails/subtitles/chapters into the final file, and remuxing between containers (MP4 \u21c4 MKV). Without it, yt-dlp can still download pre-merged low-quality formats, but you lose almost every \"advanced\" feature.\n\nyt-dlp's own documentation lists ffmpeg and ffprobe as required for merging separate video/audio files and for various post-processing tasks, and specifically warns: what you need is the ffmpeg *binary*, not the Python package of the same name (`pip install ffmpeg` does NOT give you what yt-dlp needs).\n\n### Downloading official Windows builds\n\nThe yt-dlp project maintains its own FFmpeg Windows builds at `yt-dlp/FFmpeg-Builds`, which are currently equivalent to upstream FFmpeg (no more custom patches applied). You have two good sources:\n\n- **yt-dlp/FFmpeg-Builds** (GitHub): `github.com/yt-dlp/FFmpeg-Builds/releases` \u2014 builds specifically tested against yt-dlp's use cases.\n- **gyan.dev** Windows builds (community-maintained, widely used, also distributed via `winget install Gyan.FFmpeg`): a `full` or `essentials` build is sufficient for yt-dlp.\n\nGrab the `win64` release build (a `.zip` or `.7z` archive).\n\n### Folder layout\n\nAfter extracting, you'll see something like:\n\n```\nffmpeg-release-full\\\n\u251c\u2500\u2500 bin\\\n\u2502 \u251c\u2500\u2500 ffmpeg.exe\n\u2502 \u251c\u2500\u2500 ffprobe.exe\n\u2502 \u2514\u2500\u2500 ffplay.exe\n\u251c\u2500\u2500 doc\\\n\u2514\u2500\u2500 presets\\\n```\n\nThe only two files yt-dlp actually needs are **`ffmpeg.exe`** and **`ffprobe.exe`** from the `bin\\` folder.\n\n### PATH configuration\n\nTwo options:\n\n1. **Add `bin\\` to PATH** (same steps as \u00a72's PATH instructions) \u2014 makes `ffmpeg`/`ffprobe` runnable from anywhere and lets yt-dlp auto-detect them.\n2. **Copy `ffmpeg.exe` and `ffprobe.exe` directly into your `C:\\yt-dlp\\` folder** next to `yt-dlp.exe` \u2014 no PATH edit needed; yt-dlp checks its own directory first.\n\n### Verifying installation\n\n```powershell\nffmpeg -version\nffprobe -version\n```\n\nBoth should print a version banner. If PowerShell says `ffmpeg is not recognized`, PATH wasn't applied (see \u00a719 Troubleshooting \u2192 PATH issues) or you're using a terminal window opened before the PATH change.\n\n### Common mistakes\n\n- Installing the `ffmpeg` **PyPI package** (`pip install ffmpeg`) instead of the actual binary \u2014 this Python package does nothing useful for yt-dlp.\n- Downloading a **32-bit** FFmpeg build on a 64-bit system (works, but noticeably slower for heavy re-encodes).\n- Extracting FFmpeg into `Downloads\\` and forgetting where it is \u2014 always move it to a permanent, deliberate folder before wiring up PATH.\n- Only adding the **top-level** extracted folder to PATH instead of the `bin\\` subfolder that actually contains the `.exe` files.\n\n### How yt-dlp detects FFmpeg\n\nyt-dlp looks for `ffmpeg`/`ffprobe` in this order: (1) the location you set with `--ffmpeg-location PATH` (either the exe's folder or the exe itself), (2) yt-dlp's own directory (useful for portable installs), (3) your system `PATH`. If you have multiple FFmpeg installs (e.g. one bundled with another app like OBS or Audacity), an old/incompatible one earlier in PATH can silently get picked up \u2014 use `--ffmpeg-location` explicitly to be sure, or check which one wins with `where ffmpeg` in PowerShell/CMD.\n\n### Using portable FFmpeg\n\n```powershell\nyt-dlp --ffmpeg-location \"C:\\yt-dlp\\ffmpeg.exe\" \"URL\"\n# or point at the containing folder\nyt-dlp --ffmpeg-location \"C:\\ffmpeg\\bin\" \"URL\"\n```\n\nPut this in your config file (\u00a77) so you never have to type it again.\n\n### Troubleshooting missing FFmpeg errors\n\n| Symptom | Cause | Fix |\n|---|---|---|\n| `WARNING: You have requested merging of multiple formats but ffmpeg is not installed` | FFmpeg not found on PATH or in yt-dlp's folder | Install FFmpeg (above) or pass `--ffmpeg-location` |\n| Downloads succeed but stay as separate `.f137` / `.f251` files | Same as above \u2014 no merge happened | Same fix; delete the leftover partial files and re-run |\n| `ffprobe not found`, metadata/duration missing | Only `ffmpeg.exe` was placed, `ffprobe.exe` forgotten | Copy `ffprobe.exe` alongside `ffmpeg.exe` |\n| `Postprocessing: Error opening output file` | Corrupt/incompatible FFmpeg build (rare 32-bit or ancient build) | Redownload a current `win64` build |\n\n---\n\n## 4. Windows Terminal: CMD vs. PowerShell vs. Windows Terminal\n\n**Windows Terminal** is just the modern *host application* (tabs, GPU rendering, profiles) \u2014 inside it you still run either **Command Prompt (cmd.exe)** or **PowerShell**. It's the recommended way to run yt-dlp day-to-day because it's fast, supports Unicode properly, and lets you keep multiple sessions in tabs.\n\n| | Command Prompt (cmd.exe) | PowerShell | Windows Terminal |\n|---|---|---|---|\n| Quoting | Double quotes `\"...\"` only | Double **or** single quotes | Depends on which shell tab you're in |\n| Variables | `%VARNAME%` | `$env:VARNAME` | Same as underlying shell |\n| Unicode filename support | Weak by default (needs `chcp 65001`) | Good | Good (host renders UTF-8 natively) |\n| Scripting | `.bat` | `.ps1` (far more powerful) | N/A \u2014 it's just the window |\n| Recommended for | Quick one-off commands | Automation, scripts, loops | Everyday driver, houses either shell |\n\n### Quoting rules\n\n- **PowerShell**: prefer **double quotes** for URLs/paths containing `$`-like characters that you don't want expanded, and single quotes when you want the string completely literal. Note that on Windows you may need to use double quotes instead of single quotes compared to Linux/macOS examples you'll find online \u2014 this trips up almost everyone copying commands from a Mac/Linux tutorial.\n ```powershell\n yt-dlp -f \"bv*+ba/b\" \"https://youtu.be/XXXXXXXXXXX\"\n ```\n- **CMD**: only double quotes work reliably; you cannot nest them, and `%` needs doubling (`%%`) inside batch files (but not when typed interactively).\n\n### Escaping characters\n\n- URLs with `&` (common in YouTube playlist URLs) **must** be quoted in both shells, or CMD/PowerShell will interpret `&` as a command separator and truncate the URL.\n ```powershell\n yt-dlp \"https://www.youtube.com/watch?v=XXXXXXXXXXX&list=PLxxxxxxxx\"\n ```\n- In PowerShell, a literal `$` inside double quotes needs a backtick: `` `$ ``. Inside single quotes, `$` is always literal.\n- Format selectors with square brackets (`[height<=1080]`) must be quoted in both shells \u2014 unquoted brackets can be misparsed.\n\n### File paths\n\n- Always quote paths with spaces: `-P \"C:\\Users\\Itachi\\My Videos\"`.\n- Both `\\` and `/` work as path separators in yt-dlp's own path-handling, but native Windows tools (and copy-paste from Explorer) will give you `\\`.\n- Prefer `~` or `%USERPROFILE%`/`$env:USERPROFILE` over hardcoding `C:\\Users\\yourname\\...` so configs are portable across machines.\n\n### Unicode filenames\n\nyt-dlp handles Unicode titles (Japanese, Korean, emoji, etc.) correctly by default. Two Windows-specific gotchas:\n\n1. **CMD's legacy code page** can mis-render Unicode in the terminal *display* (cosmetic only \u2014 the actual saved filename is still correct). Run `chcp 65001` first, or just use PowerShell/Windows Terminal, which handles UTF-8 natively.\n2. **NTFS forbids certain characters** in filenames (`\\ / : * ? \" < > |`) that are legal in video titles. yt-dlp automatically sanitizes these on Windows by default \u2014 see \u00a78 for how this affects your output templates.\n\n### Environment variables\n\n| Shell | Syntax | Example |\n|---|---|---|\n| CMD | `%VAR%` | `%USERPROFILE%\\Videos` |\n| PowerShell | `$env:VAR` | `$env:USERPROFILE\\Videos` |\n| Inside yt-dlp options (`-o`, `-P`, `--config-locations`, etc.) | `%VAR%` **or** `${VAR}` | yt-dlp allows using UNIX-style `${VARIABLE}` syntax on Windows for path-like options such as `--output` and `--config-locations` |\n\nOn Windows, `${USERPROFILE}` generally points to `C:\\Users\\` and `${APPDATA}` to `${USERPROFILE}\\AppData\\Roaming` \u2014 these are the two variables you'll use constantly for config files and output folders.\n\n---\n\n## 5. Basic Usage\n\n*(Beginner level \u2014 this section assumes yt-dlp and FFmpeg are already installed and on PATH.)*\n\n### Downloading a single video\n\n```powershell\nyt-dlp \"https://www.youtube.com/watch?v=XXXXXXXXXXX\"\n```\n\n### Downloading a playlist\n\n```powershell\nyt-dlp \"https://www.youtube.com/playlist?list=PLxxxxxxxxxxxxxxxx\"\n```\n\n### Downloading a channel (all uploads)\n\n```powershell\nyt-dlp \"https://www.youtube.com/@ChannelName/videos\"\n```\n\n### Downloading a livestream archive (already-ended stream, VOD)\n\n```powershell\nyt-dlp \"https://www.youtube.com/watch?v=LIVESTREAM_ID\"\n```\n\nFor a **currently live** stream, yt-dlp will wait and record from the current point unless you add `--live-from-start` to capture from the beginning (site support required; YouTube supports this).\n\n```powershell\nyt-dlp --live-from-start \"https://www.youtube.com/watch?v=LIVE_ID\"\n```\n\n### Downloading Shorts\n\nShorts are just regular videos under a different URL path \u2014 no special flag needed:\n\n```powershell\nyt-dlp \"https://www.youtube.com/shorts/XXXXXXXXXXX\"\n```\n\n### Audio extraction\n\n```powershell\nyt-dlp -x --audio-format mp3 \"URL\"\n```\n\n`-x` (`--extract-audio`) downloads the best audio-only stream and converts it (via FFmpeg) to the format given by `--audio-format`. See \u00a712 for all supported formats.\n\n### Metadata, thumbnails, chapters (all beginner-friendly flags)\n\n```powershell\nyt-dlp --embed-metadata --embed-thumbnail --embed-chapters \"URL\"\n```\n\n### Subtitles\n\n```powershell\n# Manual (human-written) subtitles only, English\nyt-dlp --write-subs --sub-langs en \"URL\"\n\n# Auto-generated subtitles (YouTube's ASR captions)\nyt-dlp --write-auto-subs --sub-langs en \"URL\"\n```\n\n### Resuming interrupted downloads\n\nyt-dlp resumes partial downloads **by default** \u2014 if a `.part` file exists from a previous run, re-running the same command continues instead of restarting. To explicitly disable/force this:\n\n```powershell\nyt-dlp --continue \"URL\" # (default behavior, explicit)\nyt-dlp --no-continue \"URL\" # force restart from scratch\n```\n\n### Playlist handling basics\n\n```powershell\n# Only the 5th item\nyt-dlp --playlist-items 5 \"PLAYLIST_URL\"\n\n# A range\nyt-dlp --playlist-items 1-10 \"PLAYLIST_URL\"\n\n# Skip the first 3 (start at #4)\nyt-dlp --playlist-start 4 \"PLAYLIST_URL\"\n```\n\nMore playlist power-tools are in \u00a711.\n\n---\n\n## 6. Format Selection\n\n*(Intermediate/Advanced \u2014 this is the single most powerful part of yt-dlp.)*\n\n### `-F` \u2014 list all available formats\n\nAlways run this first when you want a *specific* quality/codec:\n\n```powershell\nyt-dlp -F \"URL\"\n```\n\nOutput looks like:\n\n```\nID EXT RESOLUTION FPS CH \u2502 FILESIZE TBR PROTO \u2502 VCODEC VBR ACODEC ABR ASR MORE INFO\n137 mp4 1920x1080 30 \u2502 ~120.5MiB ... https \u2502 avc1.640028 ... video only\n251 webm audio only \u2502 ~ 8.1MiB ... https \u2502 opus 160k\n```\n\n- `bv`/`bestvideo` selectors work with **video-only** rows.\n- `ba`/`bestaudio` selectors work with **audio-only** rows.\n- Combined (\"pre-merged\") rows have both a VCODEC and ACODEC filled in.\n\n### `-f` \u2014 select a format\n\n```powershell\n# Download and merge the best video-only + best audio-only,\n# falling back to best combined if separate streams aren't offered\nyt-dlp -f \"bv+ba/b\" \"URL\"\n\n# Same, but skip merging if the video already has audio built in\nyt-dlp -f \"bv*+ba/b\" \"URL\"\n```\n\nThese two idiomatic patterns \u2014 `bv+ba/b` and `bv*+ba/b` \u2014 are the officially documented recommended selectors, and running yt-dlp with no `-f` flag at all defaults to the same behavior.\n\nCommon filtered selectors:\n\n```powershell\nyt-dlp -f \"bv*[height<=1080]+ba/b[height<=1080]\" \"URL\" # cap at 1080p\nyt-dlp -f \"bv*[height<=2160]+ba/b[height<=2160]\" \"URL\" # cap at 4K\nyt-dlp -f 137 \"URL\" # specific format ID from -F\nyt-dlp -f \"22\" \"URL\" # specific pre-merged format ID\n```\n\nYou can also select by codec:\n\n```powershell\nyt-dlp -f \"bv*[vcodec^=avc1]+ba[acodec^=mp4a]\" \"URL\" # force H.264 video + AAC audio\nyt-dlp -f \"bv*[vcodec^=av01]+ba\" \"URL\" # force AV1 video\n```\n\nGrouping with parentheses lets you fall back between whole containers: `-f \"(mp4,webm)[height<480]\"` downloads the best pre-merged mp4 or webm format under 480p.\n\n### `-S` \u2014 format sorting (the recommended approach over rigid `-f` filters)\n\nInstead of hard *filtering*, `-S` re-orders yt-dlp's own \"best\" ranking, so you still get automatic fallback if your preferred codec/resolution isn't available. The general syntax is `--format-sort field1,field2,...`, and you can force your custom order to override the built-in defaults entirely with `--format-sort-force`.\n\nKey sortable fields:\n\n| Field | Meaning | Default preference order |\n|---|---|---|\n| `res` | Resolution (height) | Higher is better |\n| `fps` | Frame rate | Higher is better |\n| `vcodec` | Video codec | av01 > vp9.2 > vp9 > h265 > h264 > vp8 > h263 > theora > other |\n| `acodec` | Audio codec | flac/alac > wav/aiff > opus > vorbis > aac > mp4a > mp3 > ac4 > eac3 > ac3 > dts > other |\n| `hdr` | Dynamic range | SDR preferred over HDR by default (`hdr:12` \u2014 Dolby Vision specifically is *not* preferred by default since DV isn't fully compatible with most devices) |\n| `ext` | Container extension | Video: mp4 > mov > webm > flv > other (webm wins instead if `--prefer-free-formats` is set) |\n| `size`, `br` | Filesize / bitrate | Higher is better |\n| `proto` | Download protocol | https/ftps > http/ftp > m3u8_native/m3u8 > http_dash_segments > websocket_frag > f4f/f4m |\n\nThe full built-in default sort order (when you don't specify `-S` at all) is: `lang,quality,res,fps,hdr:12,vcodec,channels,acodec,size,br,asr,proto,ext,hasaud,source,id`. `hasvid` and `ie_pref` always take top priority regardless of your custom order, unless you pass `--format-sort-force`.\n\n**Practical examples:**\n\n```powershell\n# Prefer H.264 video and AAC audio (max device compatibility), any resolution\nyt-dlp -S \"vcodec:h264,acodec:aac\" -f \"bv+ba/b\" \"URL\"\n\n# Cap resolution at 1080p while still sorting by codec preference (this guide's default)\nyt-dlp -S \"res:1080,vcodec:h264,acodec:aac\" -f \"bv+ba/b\" \"URL\"\n\n# Prefer smallest file size instead of best quality (rare, but useful for slow connections)\nyt-dlp -f best -S \"+size,+br,+res,+fps\" \"URL\"\n```\n\nNote: if you use `-f worst`, yt-dlp picks the format that's worst in *every* respect at once, which usually isn't what you want \u2014 `-S \"+size,+br,+res,+fps\"` with `-f best` is the documented, better alternative for \"smallest reasonable file.\"\n\n### Merging & container selection: MP4 vs. MKV\n\n```powershell\n--merge-output-format mkv # container used ONLY when a merge is actually required\n--remux-video mkv # additionally re-container a video that's already combined\n```\n\n`--merge-output-format` accepts one of `mkv, mp4, ogg, webm, flv`, and is ignored entirely if no merge is required in the first place \u2014 this is why the TL;DR config also sets `--remux-video mkv`: it guarantees MKV even for videos that came pre-merged and never needed FFmpeg's merger.\n\n**Why this guide defaults to MKV over MP4:**\n\n| | MKV | MP4 |\n|---|---|---|\n| Codec flexibility | Accepts virtually any video/audio codec combo (AV1, VP9, Opus, etc.) without re-encoding | Stricter \u2014 some codec combos (e.g. VP9+Opus) either don't fit or need re-encoding to be \"valid\" MP4 |\n| Chapters/subtitles/multiple audio tracks | Native, robust support | Supported but more finicky |\n| Compatibility with old hardware/software (TVs, some phones, video editors) | Weaker | Much stronger \u2014 nearly universal |\n| Streaming-friendly / web players | Weaker | Stronger |\n\n**Rule of thumb**: MKV if you're archiving on a PC/NAS and want zero quality loss from container juggling (this guide's default); MP4 if the file needs to play on a smart TV, phone, or be re-uploaded/edited elsewhere \u2014 in which case swap `mkv` for `mp4` in the config from the TL;DR.\n\nTo specify multiple fallback rules for `--remux-video`/`--recode-video`: e.g. `\"aac>m4a/mov>mp4/mkv\"` remuxes aac to m4a, mov to mp4, and anything else to mkv.\n\n### \"Or the original\" \u2014 grabbing untouched maximum quality\n\nSometimes you don't want the 1080p cap \u2014 you want whatever the uploader actually published, uncapped:\n\n```powershell\nyt-dlp -f \"bv*+ba/b\" -S \"res,vcodec:h264,acodec:aac\" --merge-output-format mkv \"URL\"\n```\n\nDropping the `:1080` from `res` removes the height cap entirely while keeping your codec preference \u2014 yt-dlp will grab the highest resolution the site actually offers (4K/8K if available) and merge it into MKV.\n\n---\n\n## 7. Configuration Files\n\n*(Intermediate)*\n\n### Locations on Windows, in load order\n\nyt-dlp reads config files from multiple locations and merges them (later ones can override earlier ones); **command-line arguments always win over any config file.**\n\n| Priority | Location | Notes |\n|---|---|---|\n| 1. Command line | n/a | Always wins |\n| 2. Portable config | `yt-dlp.conf` next to `yt-dlp.exe` | Recommended specifically for portable installations \u2014 the config travels with the executable |\n| 3. User config (primary) | `%APPDATA%\\yt-dlp\\config.txt` | The usual/most common location on Windows |\n| 4. User config (alt) | `%APPDATA%\\yt-dlp\\config` (no extension) | Also read; `config.txt` and `config` are both valid names |\n| 5. System config | none by default on Windows (Unix has `/etc/yt-dlp.conf`) | Rare to use on Windows |\n\nOn Windows, `~` resolves to `${HOME}` if it's set, or otherwise to `${USERPROFILE}` / `${HOMEDRIVE}${HOMEPATH}`.\n\n### Confirming what actually loaded\n\n```powershell\nyt-dlp -v \"URL\" 2>&1 | Select-String -Pattern \"config\"\n```\n\nRunning any command with `-v` (verbose) prints the paths of every config file yt-dlp loaded, near the top of the output \u2014 this is the fastest way to debug \"my config isn't applying\" issues.\n\n### `--config-locations` \u2014 multiple/custom config files\n\n```powershell\n# Load one specific config file only, ignoring the default search\nyt-dlp --config-locations \"C:\\yt-dlp\\music.conf\" \"URL\"\n\n# Combine several\nyt-dlp --config-locations \"C:\\yt-dlp\\base.conf\" --config-locations \"C:\\yt-dlp\\mkv.conf\" \"URL\"\n```\n\n`--config-locations` can also be used *inside* another config file to chain-load additional configs. This is how power users build \"profiles\" \u2014 e.g. a `base.conf` with paths/archive settings, plus a swappable `audio.conf` or `mkv.conf` for per-task overrides. A tidy way to invoke these from PowerShell is wrapping them in a function, e.g. `function yt-music { yt-dlp --config-locations ~/.config/yt-dlp/music.conf $args }` (translate the path to a Windows one \u2014 see \u00a717 for a full PowerShell profile example).\n\nTo bypass **all** config files for one run: `yt-dlp --ignore-config -f best \"URL\"` (also documented as the way to override configs on a per-command basis).\n\n### Fully commented ideal Windows configuration\n\nSave this as `%APPDATA%\\yt-dlp\\config.txt`:\n\n```ini\n# ============================================================\n# yt-dlp configuration \u2014 Windows\n# Location: %APPDATA%\\yt-dlp\\config.txt\n# One option per line, written exactly as on the command line\n# (without the leading \"yt-dlp\"). Lines starting with # are comments.\n# ============================================================\n\n# ---- Format & container: MKV, cap 1080p, best audio -------\n# Prefer 1080p, H.264 video (max compatibility), AAC audio\n-S \"res:1080,vcodec:h264,acodec:aac\"\n# Only used if a merge is actually required\n--merge-output-format mkv\n# Force MKV even for videos that arrive pre-merged\n--remux-video mkv\n\n# ---- Output location & naming ------------------------------\n-P \"~/Videos/yt-dlp\"\n-o \"%(uploader)s/%(title)s [%(id)s].%(ext)s\"\n\n# ---- Metadata / thumbnails / chapters -----------------------\n--embed-metadata\n--embed-thumbnail\n--embed-chapters\n--add-metadata\n\n# ---- Subtitles ------------------------------------------------\n--write-subs\n--sub-langs \"en.*\"\n--embed-subs\n\n# ---- Don't re-download things you already have ---------------\n--download-archive \"~/Videos/yt-dlp/archive.txt\"\n\n# ---- Networking / reliability ---------------------------------\n--retries 10\n--fragment-retries 10\n--concurrent-fragments 4\n\n# ---- Misc quality-of-life --------------------------------------\n--no-mtime # keep the actual download date, not the upload date, as file timestamp\n--restrict-filenames # ASCII-only filenames (optional; remove if you want Unicode titles as-is)\n```\n\nRemove `--restrict-filenames` if you're fine with Unicode characters directly in filenames (modern Windows/NTFS handles them fine \u2014 see \u00a74 and \u00a720).\n\n---\n\n## 8. Output Templates\n\n*(Intermediate)*\n\n### Template syntax basics\n\nOutput templates use `%(fieldname)s` (string), `%(fieldname)d` (integer), or `%(fieldname)05d` (zero-padded integer) syntax, set with `-o`/`--output`.\n\n```powershell\nyt-dlp -o \"%(title)s.%(ext)s\" \"URL\"\n```\n\n### Commonly used fields\n\n| Field | Meaning |\n|---|---|\n| `%(title)s` | Video title |\n| `%(id)s` | Unique video ID |\n| `%(ext)s` | File extension (set automatically \u2014 never hardcode this) |\n| `%(uploader)s` | Channel/uploader name |\n| `%(upload_date)s` | `YYYYMMDD` |\n| `%(playlist)s` | Playlist name (empty if not part of one) |\n| `%(playlist_index)s` | Position within playlist |\n| `%(duration)s` / `%(duration_string)s` | Length in seconds / `HH:MM:SS` |\n| `%(resolution)s` | e.g. `1920x1080` |\n| `%(channel)s` | Channel name (site-dependent, may differ from uploader) |\n\n### Date formatting\n\n```powershell\nyt-dlp -o \"%(upload_date>%Y-%m-%d)s - %(title)s.%(ext)s\" \"URL\"\n```\n\nThe `>` syntax reformats a `strftime`-compatible field \u2014 `upload_date` is normally `YYYYMMDD`, and `>%Y-%m-%d` converts it to `2026-07-14`-style.\n\n### Nested folders / organization by playlist and channel\n\n```powershell\n# Organize by uploader, then playlist name if present\nyt-dlp -o \"%(uploader)s/%(playlist|Singles)s/%(title)s [%(id)s].%(ext)s\" \"URL\"\n```\n\nThe `|default` syntax (`%(playlist|Singles)s`) substitutes a fallback value (\"Singles\") when the field is empty \u2014 handy for videos that aren't part of any playlist.\n\nA common full pattern for a well-organized archive is `-o \"%(uploader)s/%(playlist|)s/%(upload_date>%Y-%m-%d)s - %(title)s [%(id)s].%(ext)s\"`.\n\n### Filename sanitization & Windows filename limitations\n\nyt-dlp **automatically sanitizes** filenames on Windows, stripping/replacing the characters NTFS forbids (`\\ / : * ? \" < > |`) and trimming trailing dots/spaces. Two extra flags matter here:\n\n- `--restrict-filenames`: forces ASCII-only, replaces spaces with underscores, strips special characters more aggressively \u2014 safest for scripts, USB drives formatted FAT32, or cross-platform syncing (e.g. via OneDrive to a Mac).\n- `--windows-filenames`: forces Windows-safe sanitization rules even when running yt-dlp on Linux/macOS (useful if you're producing files that will later be copied to a Windows machine); on Windows itself this is already the default behavior.\n\n**Path length**: classic Windows paths are capped at 260 characters (`MAX_PATH`) unless long-path support is enabled (see \u00a720). Long, deeply-nested `-o` templates (playlist name + uploader + long title) can hit this limit \u2014 if downloads randomly fail with a \"file not found\"/\"cannot create file\" error, this is usually why.\n\n### Practical examples\n\n```powershell\n# Flat, simple\nyt-dlp -o \"%(title)s [%(id)s].%(ext)s\" \"URL\"\n\n# By channel\nyt-dlp -o \"%(uploader)s/%(title)s.%(ext)s\" \"URL\"\n\n# By channel + upload year\nyt-dlp -o \"%(uploader)s/%(upload_date>%Y)s/%(title)s.%(ext)s\" \"URL\"\n\n# Playlist, numbered\nyt-dlp -o \"%(playlist)s/%(playlist_index)03d - %(title)s.%(ext)s\" \"PLAYLIST_URL\"\n\n# Audio library style\nyt-dlp -x --audio-format flac -o \"%(artist|uploader)s/%(album|Singles)s/%(title)s.%(ext)s\" \"URL\"\n```\n\n---\n\n## 9. Authentication\n\n*(Intermediate/Advanced)*\n\n### Browser cookies (`--cookies-from-browser`) \u2014 recommended method\n\nThis is the officially recommended way to authenticate on Windows \u2014 no manual cookie export needed:\n\n```powershell\nyt-dlp --cookies-from-browser chrome \"URL\"\nyt-dlp --cookies-from-browser firefox \"URL\"\nyt-dlp --cookies-from-browser edge \"URL\"\nyt-dlp --cookies-from-browser brave \"URL\"\n```\n\nSupported browser keywords include `brave`, `chrome`, `chromium`, `edge`, `firefox`, `opera`, `safari`, `vivaldi`, `whale`. On Windows, the Chromium-based browsers (Chrome/Edge/Brave/etc.) encrypt their cookie store using Windows DPAPI, tied to your Windows user account \u2014 yt-dlp decrypts it automatically as long as it's run under the *same* Windows user and the browser isn't set to a non-default profile without specifying it.\n\n**Selecting a specific profile / keyring:**\n\n```powershell\nyt-dlp --cookies-from-browser \"chrome:Profile 2\" \"URL\"\n```\n\n**Important caveat**: close the browser (or at least the relevant profile) before running yt-dlp \u2014 Chromium-based browsers lock the cookie database file while running, which can cause `--cookies-from-browser` to fail or grab stale cookies.\n\n### Exported cookie files (`--cookies`)\n\nIf you'd rather export cookies manually (e.g. using a browser extension like \"Get cookies.txt\"), in Netscape format:\n\n```powershell\nyt-dlp --cookies \"C:\\yt-dlp\\cookies.txt\" \"URL\"\n```\n\nThis avoids the \"browser must be closed\" issue and works well for scheduled tasks that run while you're actively using your browser (see \u00a717).\n\n### Login sessions / private videos / members-only content\n\nFor content requiring a logged-in session (private videos shared with your account, YouTube members-only posts, etc.), `--cookies-from-browser` using a session where you're already logged in is the standard approach \u2014 yt-dlp does **not** have a general-purpose username/password login for most sites (a few sites support `--username`/`--password`/`--netrc`, but YouTube specifically does not accept direct credentials \u2014 Google blocks programmatic logins).\n\n### Age-restricted videos\n\nAge-gated YouTube videos generally require a logged-in, age-verified account's cookies (`--cookies-from-browser`) to bypass \u2014 there's no separate \"age flag.\"\n\n### Authentication limitations\n\n- Cookies **expire** \u2014 if downloads that previously worked start failing with 403s or \"private video\" errors, re-export/re-grab cookies from a fresh browser session.\n- Google/YouTube actively fight automated cookie extraction; if a site changes its auth flow, this can break until yt-dlp ships a patch \u2014 check `github.com/yt-dlp/yt-dlp/issues` for current known issues before assuming your setup is broken.\n- 2FA-protected accounts: log in normally in the browser first (2FA happens there), then point yt-dlp at that browser's cookies \u2014 yt-dlp itself never handles 2FA prompts.\n- Never share `cookies.txt` \u2014 it grants full account session access to whoever has the file.\n\n---\n\n## 10. Batch Downloads\n\n*(Beginner/Intermediate)*\n\n### URL text files\n\n```powershell\nyt-dlp -a \"C:\\yt-dlp\\urls.txt\"\n```\n\nWhere `urls.txt` has one URL per line; lines starting with `#`, `;`, or `]` are treated as comments and skipped.\n\n### Download archives (avoid re-downloading)\n\n```powershell\nyt-dlp --download-archive \"C:\\yt-dlp\\archive.txt\" \"PLAYLIST_URL\"\n```\n\nyt-dlp records every successfully downloaded video ID in `archive.txt`. Re-running the exact same command later \u2014 e.g. against a channel that's gained new uploads \u2014 will **skip everything already in the archive** and only fetch new videos. This is the backbone of \"incremental\" channel/playlist syncing.\n\n### Incremental downloads (channel/playlist sync pattern)\n\n```powershell\nyt-dlp --download-archive \"archive.txt\" -o \"%(uploader)s/%(title)s.%(ext)s\" \"https://www.youtube.com/@ChannelName/videos\"\n```\n\nRun this same command on a schedule (\u00a717) \u2014 each run only pulls what's new since the last run.\n\n### Scheduled downloads / automation\n\nCovered fully in \u00a717 (Windows Task Scheduler, `.ps1` scripts).\n\n---\n\n## 11. Playlists\n\n*(Intermediate)*\n\n### Partial downloads / range selection\n\n```powershell\nyt-dlp --playlist-items 1,3,5-10 \"PLAYLIST_URL\"\n```\n\n`--playlist-items` accepts individual indices and ranges combined with commas, e.g. `1,3,5-10`.\n\n### Reverse order\n\n```powershell\nyt-dlp --playlist-reverse \"PLAYLIST_URL\"\n```\n\nThis downloads the playlist starting from the last item instead of the first \u2014 useful for playlists that list newest-first, when you want chronological download order.\n\n### Skipping duplicates across runs\n\nCombine `--download-archive` (see \u00a710) with a stable output template \u2014 the archive is what actually prevents duplicate downloads; the output template just keeps files organized.\n\n### Updating playlists efficiently\n\nThe efficient pattern for \"give me only what's new since last time\":\n\n```powershell\nyt-dlp --download-archive \"archive.txt\" --playlist-reverse \"PLAYLIST_URL\"\n```\n\n`--playlist-reverse` combined with an archive means yt-dlp processes oldest-to-newest and skips everything already recorded \u2014 new uploads simply get appended at the end of each future run.\n\n### Skipping already-downloaded items without a full archive scan\n\n```powershell\nyt-dlp --break-on-existing --download-archive \"archive.txt\" \"PLAYLIST_URL\"\n```\n\n`--break-on-existing` stops processing the *rest* of the playlist as soon as it hits the first already-archived video \u2014 much faster for large channels where you know new content is always added at the top.\n\n---\n\n## 12. Audio Downloads\n\n*(Beginner/Intermediate)*\n\n### Supported audio formats\n\n`--audio-format` currently supports: `best` (default, no re-encode), `aac`, `alac`, `flac`, `m4a`, `mp3`, `opus`, `vorbis`, `wav`.\n\n```powershell\nyt-dlp -x --audio-format mp3 \"URL\"\nyt-dlp -x --audio-format flac \"URL\"\nyt-dlp -x --audio-format opus \"URL\"\nyt-dlp -x --audio-format aac \"URL\"\nyt-dlp -x --audio-format wav \"URL\"\nyt-dlp -x --audio-format m4a \"URL\"\n```\n\n### Which format should you actually pick?\n\n| Format | Type | When to use |\n|---|---|---|\n| `opus` | Lossy, modern | **Best quality-per-bit** \u2014 matches what YouTube usually delivers natively, so `-x --audio-format opus` often needs **zero re-encoding** (fastest, no quality loss from transcoding) |\n| `m4a`/`aac` | Lossy | Best universal device compatibility (iPhones, car stereos, older hardware) |\n| `mp3` | Lossy | Maximum compatibility with very old software; avoid unless you specifically need it \u2014 re-encoding to MP3 from Opus/AAC source loses quality |\n| `flac`/`wav` | Lossless | **Do not** meaningfully improve quality over a lossy YouTube source (YouTube audio is lossy at the source) \u2014 only useful if you plan to further edit/process the audio and want a lossless *intermediate* file |\n\n### Quality settings\n\n```powershell\nyt-dlp -x --audio-format mp3 --audio-quality 0 \"URL\" # 0 = best VBR\nyt-dlp -x --audio-format mp3 --audio-quality 320K \"URL\" # explicit CBR bitrate\n```\n\n`--audio-quality` takes a value between 0 (best) and 10 (worst) for VBR, or a specific bitrate like `128K`; the default is `5`. For best-audio-always, `--audio-quality 0` is the setting used throughout this guide's \"best audio\" default.\n\n### Metadata & thumbnail embedding\n\n```powershell\nyt-dlp -x --audio-format opus --audio-quality 0 --embed-metadata --embed-thumbnail -o \"%(artist|uploader)s - %(title)s.%(ext)s\" \"URL\"\n```\n\nNote: thumbnail embedding into `opus`/`flac` containers is fully supported via FFmpeg, but not every music player renders embedded art from every container equally well \u2014 `m4a`/`mp3` have the broadest player support for embedded cover art.\n\n---\n\n## 13. Subtitle Downloads\n\n*(Beginner/Intermediate)*\n\n### Manual (human-written) subtitles\n\n```powershell\nyt-dlp --write-subs --sub-langs en \"URL\"\n```\n\n### Auto-generated subtitles\n\n```powershell\nyt-dlp --write-auto-subs --sub-langs en \"URL\"\n```\n\n### Multiple languages\n\n```powershell\nyt-dlp --write-subs --sub-langs \"en,ja,es\" \"URL\"\n```\n\n`--sub-langs` accepts regex, e.g. `\"en.*,ja\"` matches `en`, `en-US`, `en-GB`, etc. plus `ja`, and you can prefix a language with `-` to exclude it, e.g. `\"all,-live_chat\"`.\n\n### Listing what's actually available first\n\n```powershell\nyt-dlp --list-subs \"URL\"\n```\n\n### Embedding subtitles directly into the video file\n\n```powershell\nyt-dlp --write-subs --sub-langs en --embed-subs \"URL\"\n```\n\nEmbedding into MKV supports essentially any subtitle format without conversion; MP4 embedding is pickier (generally requires `mov_text`/SRT-compatible tracks, which yt-dlp handles automatically via FFmpeg conversion when needed).\n\n### Converting subtitle formats\n\n```powershell\nyt-dlp --write-subs --sub-format srt --sub-langs en \"URL\"\n# or convert whatever was downloaded afterward\nyt-dlp --write-subs --sub-langs en --convert-subs srt \"URL\"\n```\n\n`--sub-format` accepts a preference list separated by `/`, e.g. `\"srt\"` or `\"ass/srt/best\"`.\n\n---\n\n## 14. Metadata\n\n*(Intermediate)*\n\n### Embedding metadata into the file\n\n```powershell\nyt-dlp --embed-metadata \"URL\"\n```\n\nWrites title, uploader, description, upload date, etc. into the container's metadata tags (readable by most media players and file managers).\n\n### Chapters\n\n```powershell\nyt-dlp --embed-chapters \"URL\"\n```\n\nPulls YouTube's chapter markers (from the description timestamps or the official chapters feature) directly into the file as navigable chapter points.\n\n### Description as a separate file\n\n```powershell\nyt-dlp --write-description \"URL\"\n```\n\n### Comments\n\n```powershell\nyt-dlp --write-comments \"URL\"\n```\n\nSaves the video's comment section into the `.info.json` (see below) \u2014 can be slow on videos with thousands of comments; combine with `--max-comments` to cap it, e.g. `--max-comments 500`.\n\n### Full JSON metadata dump\n\n```powershell\nyt-dlp --write-info-json \"URL\"\n```\n\nWrites a `.info.json` sidecar file with essentially everything yt-dlp knows about the video \u2014 every field usable in output templates, full format list, etc. Extremely useful for archival/scripting purposes. Use `--no-write-info-json` (or just omit the flag) if you don't want the extra file cluttering your download folder.\n\n### SponsorBlock as metadata\n\nCovered fully in \u00a715 \u2014 SponsorBlock chapters can be embedded the same way as regular chapters.\n\n---\n\n## 15. SponsorBlock\n\n*(Intermediate)*\n\nyt-dlp integrates directly with the community-run [SponsorBlock](https://sponsor.ajay.app/) database (originally a browser extension) to mark or cut sponsor segments, intros, outros, and other non-content sections from YouTube videos \u2014 this is an officially listed core feature of yt-dlp itself, no extension required.\n\n### Installation / requirements\n\nNo separate install \u2014 it's built into yt-dlp. FFmpeg is required for the `--sponsorblock-remove` variant (which actually cuts the video), but not for `--sponsorblock-mark` (which only adds chapter markers you can skip manually in your player).\n\n### Marking segments as chapters (non-destructive, recommended default)\n\n```powershell\nyt-dlp --sponsorblock-mark all \"URL\"\n```\n\nThis adds chapter markers for each detected segment type, letting you skip them manually in any player that supports chapters (MKV/MP4 with `--embed-chapters`, or most modern video players) \u2014 nothing is deleted from the file.\n\n### Automatically removing segments (destructive \u2014 cuts the video)\n\n```powershell\nyt-dlp --sponsorblock-remove sponsor,selfpromo,interaction \"URL\"\n```\n\nThis re-encodes the affected sections out of the file entirely via FFmpeg \u2014 slower (requires re-encoding around cut points) and **cannot be undone** later, so use `--sponsorblock-mark` if you're unsure.\n\n### Categories\n\n| Category | Meaning |\n|---|---|\n| `sponsor` | Paid promotion segments |\n| `selfpromo` | Unpaid self-promotion (merch, other channels, etc.) |\n| `interaction` | \"Like and subscribe\" reminders |\n| `intro` | Channel intro/intro animation |\n| `outro` | Endcards/outro |\n| `preview` | Recap/preview of upcoming content |\n| `music_offtopic` | Non-music sections in music videos |\n| `filler` | Tangential filler content |\n| `poi_highlight` | Highlight/point-of-interest markers |\n| `all` | All of the above |\n\n### Combining mark + remove selectively\n\n```powershell\nyt-dlp --sponsorblock-mark all --sponsorblock-remove sponsor,interaction \"URL\"\n```\n\nMarks everything as chapters, but only physically removes the `sponsor` and `interaction` categories \u2014 the rest stay as skippable chapters.\n\n### Limitations\n\n- Only works on **YouTube** \u2014 SponsorBlock's database doesn't cover other sites.\n- Coverage depends entirely on community submissions \u2014 brand-new or low-view videos may have zero segments logged, so nothing gets marked/removed even if sponsor content is present.\n- `--sponsorblock-remove` re-encodes near cut points (to keep cuts frame-accurate), so it's meaningfully slower than a straight download and can introduce a tiny quality dip right at the cut boundary \u2014 `--sponsorblock-mark` avoids this entirely.\n\n---\n\n## 16. Advanced Features\n\n*(Advanced)*\n\n### Download archive\n\nCovered in \u00a710/\u00a711 \u2014 `--download-archive FILE.txt`.\n\n### Rate limiting\n\n```powershell\nyt-dlp --limit-rate 5M \"URL\" # cap at 5 MB/s\nyt-dlp --limit-rate 500K \"URL\" # cap at 500 KB/s\n```\n\nUseful to avoid saturating your connection during large batch jobs, or to reduce the odds of being rate-limited/flagged by aggressive rate limits on the source site.\n\n### Retries\n\n```powershell\nyt-dlp --retries 10 --fragment-retries 10 \"URL\"\n```\n\n`--retries` covers whole-download retry attempts on transient network failures; `--fragment-retries` covers individual DASH/HLS fragment retries within a single download. `--retries infinite` and `--fragment-retries infinite` are also valid for unattended long-running jobs.\n\n### Concurrent fragments\n\n```powershell\nyt-dlp --concurrent-fragments 4 \"URL\"\n```\n\nDownloads up to N fragments of a DASH/HLS stream in parallel \u2014 can meaningfully speed up downloads of long/high-bitrate videos on fast connections. Going much above 4\u20138 usually hits diminishing returns and increases the odds of being rate-limited by the source server.\n\n### Sleep intervals (politeness / avoiding rate limits)\n\n```powershell\nyt-dlp --sleep-requests 1 --sleep-interval 2 --max-sleep-interval 5 \"PLAYLIST_URL\"\n```\n\n`--sleep-requests` pauses between metadata requests (extraction); `--sleep-interval`/`--max-sleep-interval` pause a random amount between actual downloads \u2014 important for large batch jobs against sites that rate-limit or flag scraping-like behavior.\n\n### Proxy support\n\n```powershell\nyt-dlp --proxy \"socks5://127.0.0.1:9050\" \"URL\" # SOCKS5, e.g. Tor\nyt-dlp --proxy \"http://127.0.0.1:8080\" \"URL\" # HTTP proxy\n```\n\n### VPN usage\n\nNo special yt-dlp flag needed \u2014 a system-level VPN (WireGuard, OpenVPN client, etc.) simply changes your effective IP for all traffic including yt-dlp. Useful for geo-blocked content (see \u00a719) but subject to the same ToS/legal caveats as \u00a71.\n\n### Custom headers, Referer, User-Agent\n\n```powershell\nyt-dlp --add-header \"Referer:https://example.com\" --user-agent \"Mozilla/5.0 ...\" \"URL\"\n```\n\nOccasionally required for sites that check Referer/User-Agent as a basic anti-hotlinking measure.\n\n### External downloaders / aria2c integration\n\n```powershell\nyt-dlp --downloader aria2c --downloader-args \"aria2c:-x 16 -s 16 -k 1M\" \"URL\"\n```\n\nDelegates the actual byte-fetching to `aria2c` (must be installed separately, e.g. `winget install aria2.aria2` or `scoop install aria2`) for multi-connection, resumable downloading \u2014 can substantially speed up large single-file downloads over a fast connection. **Important**: aria2c support for downloading HLS and DASH formats was removed due to a security vulnerability (CVE-2026-50574, arbitrary code execution via manifest downloads); users affected by this change should migrate to `-N`/`--concurrent-fragments` for concurrent fragment downloads via yt-dlp's native downloader instead \u2014 aria2c remains fine for plain progressive/HTTP downloads, just not HLS/DASH manifests.\n\n---\n\n## 17. Automation (Windows Task Scheduler & Scripts)\n\n*(Advanced)*\n\n### A reusable PowerShell wrapper script\n\nSave as `C:\\yt-dlp\\sync-channels.ps1`:\n\n```powershell\n# sync-channels.ps1 \u2014 run periodically via Task Scheduler\n$ytdlp = \"C:\\yt-dlp\\yt-dlp.exe\"\n$config = \"$env:APPDATA\\yt-dlp\\config.txt\"\n$log = \"C:\\yt-dlp\\logs\\sync-$(Get-Date -Format 'yyyy-MM-dd').log\"\n\nNew-Item -ItemType Directory -Force -Path (Split-Path $log) | Out-Null\n\n# First, self-update\n& $ytdlp -U *>> $log\n\n# Then sync a list of channels/playlists, each using the shared archive file\n$urls = Get-Content \"C:\\yt-dlp\\watchlist.txt\"\nforeach ($url in $urls) {\n & $ytdlp --config-locations $config $url *>> $log\n}\n```\n\n`watchlist.txt` is just one channel/playlist URL per line.\n\n### Registering it in Task Scheduler\n\n```powershell\n$action = New-ScheduledTaskAction -Execute \"powershell.exe\" `\n -Argument \"-NoProfile -ExecutionPolicy Bypass -File `\"C:\\yt-dlp\\sync-channels.ps1`\"\"\n$trigger = New-ScheduledTaskTrigger -Daily -At 3am\n$settings = New-ScheduledTaskSettingsSet -StartWhenAvailable -WakeToRun\nRegister-ScheduledTask -TaskName \"yt-dlp Channel Sync\" -Action $action -Trigger $trigger -Settings $settings\n```\n\nOr via the GUI: **Task Scheduler \u2192 Create Task\u2026 \u2192 Triggers: Daily at 3 AM \u2192 Actions: Start a program \u2192 `powershell.exe` with the argument above \u2192 Conditions: uncheck \"Start the task only if the computer is on AC power\" if this is a laptop.**\n\n### A simple `.bat` alternative (if you prefer not to touch PowerShell scripting)\n\n```bat\n@echo off\ncd /d C:\\yt-dlp\nyt-dlp.exe -U\nyt-dlp.exe --config-locations \"%APPDATA%\\yt-dlp\\config.txt\" \"https://www.youtube.com/@ChannelName/videos\"\n```\n\nDouble-click-able, and schedulable the same way via Task Scheduler pointing directly at the `.bat` file.\n\n### Automatic updates\n\nAdding `yt-dlp -U` as the first line of any scheduled script (as above) keeps yt-dlp current without you having to remember \u2014 important, since YouTube/other sites frequently break older versions within weeks.\n\n### Automatic backups of your archive/config\n\n```powershell\n# Add near the top of sync-channels.ps1\nCopy-Item \"C:\\yt-dlp\\watchlist.txt\" \"C:\\yt-dlp\\backups\\watchlist-$(Get-Date -Format yyyyMMdd).txt\" -Force\nCopy-Item \"$env:APPDATA\\yt-dlp\\config.txt\" \"C:\\yt-dlp\\backups\\config-$(Get-Date -Format yyyyMMdd).txt\" -Force\n```\n\nA `--download-archive` file in particular is worth backing up \u2014 losing it means yt-dlp will happily re-download everything it already has on the next sync.\n\n### Quick shell aliases/functions (PowerShell profile)\n\nAdd to `$PROFILE` (open it with `notepad $PROFILE`, creating the file if it doesn't exist):\n\n```powershell\nfunction ytv { yt-dlp @args }\nfunction yta { yt-dlp -x --audio-format opus --audio-quality 0 @args }\nfunction ytbest { yt-dlp -f \"bv*+ba/b\" -S \"res,vcodec:h264,acodec:aac\" --merge-output-format mkv @args }\n```\n\nReload with `. $PROFILE`, then just run `yta \"URL\"` for a quick audio grab.\n\n---\n\n## 18. Performance Optimization\n\n*(Intermediate/Advanced)*\n\n### Faster downloads\n\n- `--concurrent-fragments 4` (or higher on very fast connections) for DASH/HLS streams \u2014 see \u00a716.\n- Prefer `https` protocol formats over `m3u8`/HLS when both are offered at the same quality (`-S proto` puts this first by default already).\n- Use `aria2c` as an external downloader for large **progressive** (non-DASH) files (\u00a716) \u2014 not for HLS/DASH manifests post-CVE-2026-50574.\n\n### Parallel fragments vs. parallel *videos*\n\nyt-dlp does **not** parallelize multiple separate video downloads within a single invocation by design (it's sequential per URL/playlist item). To run several downloads truly in parallel, launch multiple `yt-dlp` processes (e.g. via separate PowerShell jobs or `Start-Process`) \u2014 but be mindful this multiplies your request rate against the source site and can trigger rate-limiting/IP flags faster.\n\n```powershell\nStart-Job { yt-dlp \"URL1\" }\nStart-Job { yt-dlp \"URL2\" }\nGet-Job | Wait-Job | Receive-Job\n```\n\n### Disk optimization\n\n- Download to an **SSD** when possible \u2014 FFmpeg's merge/remux step is I/O-heavy (reading two streams, writing one), and mechanical HDDs noticeably slow this down on long/high-bitrate videos.\n- If archiving to a slower HDD or **network drive**, download to a local SSD/temp folder first, then move the finished file \u2014 avoids write-stutter mid-download and avoids the network-drive quirks in \u00a720.\n\n### Network optimization\n\n- `--sleep-requests`/`--sleep-interval` (\u00a716) trade raw speed for reliability on large batch jobs \u2014 worth it to avoid mid-batch rate-limit bans.\n- A wired connection (or 5GHz Wi-Fi at minimum) matters more than any yt-dlp flag for 4K/8K downloads.\n\n### CPU usage\n\n- CPU load in yt-dlp itself is minimal \u2014 the heavy lifting (merging/remuxing/re-encoding) is entirely FFmpeg's job.\n- **Remuxing** (`--remux-video`, container-only changes like MP4\u2194MKV with compatible codecs) is fast and low-CPU \u2014 no re-encoding happens.\n- **Re-encoding** (`--recode-video`, or any codec conversion that isn't a simple remux) is CPU-intensive and can take far longer than the download itself on lower-end CPUs \u2014 avoid `--recode-video` unless you specifically need a codec change; prefer `--remux-video` when just changing containers.\n\n### Memory usage\n\nGenerally low (well under 500MB even for 4K/8K downloads) since yt-dlp streams to disk rather than buffering entire files in RAM \u2014 memory usage climbing significantly usually indicates an unrelated issue (e.g. `--write-comments` on a video with an enormous comment section).\n\n---\n\n## 19. Troubleshooting\n\n*(All levels)*\n\n```mermaid\nflowchart TD\n Start[yt-dlp command failed] --> Q1{What kind of error?}\n Q1 -->|HTTP error code| HTTP[See HTTP error table]\n Q1 -->|\"command not found\"| PATH[PATH issue \u2014 see \u00a719 PATH section]\n Q1 -->|FFmpeg-related| FF[See \u00a73 FFmpeg troubleshooting]\n Q1 -->|Filename / path error| FN[Check Unicode / long-path \u2014 see \u00a720]\n Q1 -->|Login/cookie error| CK[Re-export cookies \u2014 see \u00a79]\n Q1 -->|Extraction / signature error| SIG[Update yt-dlp: yt-dlp -U]\n HTTP --> Fixed{Fixed?}\n PATH --> Fixed\n FF --> Fixed\n FN --> Fixed\n CK --> Fixed\n SIG --> Fixed\n Fixed -->|No| Issue[Search/open a GitHub issue with -vU log]\n Fixed -->|Yes| Done[Done]\n```\n\n### HTTP and extraction errors\n\n| Error | Cause | Diagnosis | Solution | Prevention |\n|---|---|---|---|---|\n| **HTTP 403 Forbidden** | Expired signature/token, missing cookies, or a site-side block | Run with `-v` and check whether it happens on extraction or on the actual byte download | Update yt-dlp (`-U`), retry, or add `--cookies-from-browser` if the content requires login | Keep yt-dlp updated; don't hammer the same video repeatedly |\n| **HTTP 429 Too Many Requests** | Rate-limited by the source site | Repeats across many URLs in a batch job | Add `--sleep-requests`/`--sleep-interval`, reduce `--concurrent-fragments`, wait before retrying | Use sleep intervals proactively on large batch jobs (\u00a716) |\n| **Signature extraction failed / unable to extract player JS** | Site changed its player/obfuscation; your yt-dlp version is behind | `yt-dlp --version` vs. latest release | `yt-dlp -U`, or reinstall via your package manager if `-U` isn't available for your install method | Update regularly; subscribe to release notifications |\n| **Unsupported URL** | Site not supported, or URL format changed | `yt-dlp --list-extractors \\| Select-String \"sitename\"` | Check if a newer yt-dlp version added support; file/search a GitHub issue | N/A |\n| **SSL / certificate errors** | Outdated CA bundle, corporate proxy MITM, or system clock skew | Try `--no-check-certificates` **temporarily** to confirm it's cert-related (do not leave this on permanently) | Update `certifi` (`pip install -U certifi` for pip installs), fix system clock, or configure corporate proxy cert properly | Keep Windows date/time synced; keep pip installs' dependencies updated |\n| **Geo-blocking** | Content restricted to certain countries | Error message explicitly mentions region restriction | Use `--proxy` or a VPN with an allowed-region exit node (subject to \u00a71's legal caveats) | N/A |\n| **Login failures with `--cookies-from-browser`** | Browser locked the cookie DB, or session expired | Close the browser fully before running; check cookies still work by browsing the site logged in | Close browser first, or export to `cookies.txt` instead (\u00a79) | Re-check cookies periodically for long-running scheduled jobs |\n| **Cookie decryption failures on Windows specifically** | Chromium's DPAPI-encrypted cookie store, run under a different Windows user/session than the browser | Confirm the script/Task Scheduler task runs as *your* Windows user, not `SYSTEM` | Set the scheduled task to run as your own user account, not SYSTEM | Configure Task Scheduler tasks with \"Run only when user is logged on\" if cookies are needed |\n\n### Windows filesystem-specific errors\n\n| Error | Cause | Diagnosis | Solution | Prevention |\n|---|---|---|---|---|\n| **FFmpeg missing / merge not happening** | See \u00a73 fully | `ffmpeg -version` in the same terminal | Install FFmpeg, set `--ffmpeg-location` | Keep FFmpeg on PATH or bundled with yt-dlp |\n| **`'yt-dlp' is not recognized as an internal or external command`** | Not on PATH, or PATH change not applied to current terminal | `where yt-dlp` (CMD) or `Get-Command yt-dlp` (PowerShell) | Re-check PATH entry (\u00a72), restart terminal, or use the full path to the `.exe` | Use winget/scoop/choco, which manage PATH automatically |\n| **Unicode filename errors (rare, mostly cosmetic)** | Legacy CMD code page | Title displays as `?????` in the terminal but the file itself is fine | Ignore, or `chcp 65001` first, or use PowerShell/Windows Terminal | Use Windows Terminal by default |\n| **Long path / \"path too long\" / \"cannot create file\"** | Output template + folder path exceeds 260 characters and long-path support isn't enabled | Try a much shorter `-o` template as a test | Enable Windows long-path support (\u00a720), or shorten the output template | Keep `-o` templates reasonably short; avoid deep nested folders |\n| **Permission denied** | Output folder in a protected location (`Program Files`, `C:\\`, OneDrive-synced folder mid-sync) | Try downloading to `%USERPROFILE%\\Downloads` as a test | Change `-P` to a folder you own, or run terminal as your normal user (not needed/recommended to run as admin) | Never install/download into `Program Files`; keep downloads in your user profile |\n| **Proxy failures** | Misconfigured `--proxy`, or corporate proxy requiring authentication yt-dlp doesn't support out of the box | Test the proxy independently (e.g. via `curl` or a browser) | Fix proxy URL/credentials format: `http://user:pass@host:port` | N/A |\n\n---\n\n## 20. Windows-Specific Tips\n\n*(Intermediate/Advanced)*\n\n### Long path support\n\nClassic Windows limits full paths to 260 characters. To lift this:\n\n1. **Group Policy** (Pro/Enterprise): `gpedit.msc` \u2192 Computer Configuration \u2192 Administrative Templates \u2192 System \u2192 Filesystem \u2192 **Enable Win32 long paths**.\n2. **Registry** (Home edition, or scripted):\n ```powershell\n New-ItemProperty -Path \"HKLM:\\SYSTEM\\CurrentControlSet\\Control\\FileSystem\" `\n -Name \"LongPathsEnabled\" -Value 1 -PropertyType DWORD -Force\n ```\n Reboot after applying.\n3. Even with long paths enabled at the OS level, **some individual applications** (older archivers, some antivirus scanners) may still choke on very long paths \u2014 keeping `-o` templates reasonably short remains good practice regardless.\n\n### NTFS limitations\n\n- Forbidden characters: `\\ / : * ? \" < > |` \u2014 yt-dlp sanitizes these automatically in filenames.\n- Reserved names (`CON`, `PRN`, `AUX`, `NUL`, `COM1`-`COM9`, `LPT1`-`LPT9`) can't be used as filenames \u2014 extremely rare to hit accidentally with video titles, but theoretically possible.\n- Trailing dots and spaces in filenames are silently stripped by Windows \u2014 yt-dlp accounts for this already.\n\n### File permissions\n\nStandard NTFS permissions apply normally; no yt-dlp-specific quirks here beyond the \"don't download into `Program Files`/system folders\" advice in \u00a719.\n\n### SmartScreen\n\nWindows SmartScreen may flag a freshly downloaded `yt-dlp.exe` as \"unrecognized app\" the first time you run it, since it's an unsigned/less-common binary with no install-base reputation yet. Click **\"More info\" \u2192 \"Run anyway\"** after verifying the checksum (\u00a72) \u2014 this is expected for many legitimate open-source CLI tools and not a sign of malware, *provided* you downloaded it from the official `github.com/yt-dlp/yt-dlp` releases page and verified the hash.\n\n### Windows Defender false positives\n\nSome antivirus engines occasionally flag `yt-dlp.exe` (a PyInstaller-bundled Python executable) as a false positive, because generic \"PyInstaller-packed binary\" heuristics are a common pattern abused by actual malware too. If Defender quarantines it:\n\n1. Re-verify the SHA256 checksum against the official release (\u00a72) \u2014 never \"just allow\" a file you haven't checked.\n2. If it checks out, add an exclusion for the specific file/folder in **Windows Security \u2192 Virus & threat protection \u2192 Manage settings \u2192 Add or remove exclusions**.\n3. If you're uneasy trusting the compiled `.exe`, use the `pip install yt-dlp` route instead \u2014 it's the same source code without a pre-built binary to worry about.\n\n### Portable installations\n\nKeep `yt-dlp.exe`, `ffmpeg.exe`, `ffprobe.exe`, and a `yt-dlp.conf` all together in one folder (\u00a72/\u00a73) for a fully self-contained, USB-drive-portable setup with zero registry/PATH dependency on the host machine \u2014 just double-check the portable config's paths (`-P`, `--download-archive`) use relative or environment-variable-based paths rather than hardcoded drive letters, since USB drive letters can change between PCs.\n\n### OneDrive interaction\n\nIf your Downloads/Videos folder is OneDrive-synced (default on many Windows 11 setups):\n\n- Large video files can trigger OneDrive to start uploading mid-download, competing for disk I/O and occasionally locking the file briefly \u2014 this can cause intermittent \"file in use\" errors during FFmpeg's merge step.\n- **Recommendation**: point `-P` at a non-synced local folder (e.g. `C:\\Downloads\\yt-dlp` or `D:\\Media`) instead, and manually move finished files into OneDrive afterward if you want them backed up.\n- If files are set to **\"Files On-Demand\"** (cloud-only placeholder), make sure the destination folder itself is fully local \u2014 writing directly into a cloud-only-placeholder folder works but adds sync overhead during active downloads.\n\n### Network drives\n\n- Downloading directly to a network share (`\\\\NAS\\Videos` or a mapped drive letter) works, but is meaningfully slower for the FFmpeg merge step (lots of read+write over the network for what's normally a fast local operation).\n- **Recommendation**: download to a local temp folder, then move (`Move-Item`) the finished file to the network location \u2014 much faster overall and avoids partial-write corruption if the network connection blips mid-download.\n- Mapped drive letters (`Z:\\`) inside scheduled tasks can be unreliable if the task runs before the drive is remapped (e.g. right after boot) \u2014 prefer full UNC paths (`\\\\NAS\\Videos\\...`) in automation scripts instead of a drive letter.\n\n---\n\n## 21. Best Practices\n\n*(All levels)*\n\n### Folder organization\n\n- One root folder per \"library\" (e.g. `D:\\Media\\YouTube\\`), with subfolders by uploader/channel via `-o` templates (\u00a78) \u2014 avoid one giant flat folder with thousands of files.\n- Keep audio-only and video downloads in separate root folders if you use both regularly \u2014 different naming conventions (artist/album vs. uploader/title) don't mix well in one tree.\n\n### Naming conventions\n\n- Always include `%(id)s` somewhere in your output template \u2014 video IDs are unique and prevent silent overwrites when two videos happen to share a title.\n- Decide once whether you want Unicode titles as-is or `--restrict-filenames` (ASCII-safe) \u2014 mixing the two across different runs makes an archive inconsistent and harder to search/sort later.\n\n### Backups\n\n- Back up your **`--download-archive`** file and **config file(s)** regularly (\u00a717) \u2014 losing the archive means re-downloading everything on the next sync.\n- The downloaded media itself is regenerable (re-run yt-dlp) as long as the source is still online; the archive/config are the only truly \"irreplaceable\" small files in this workflow.\n\n### Config management\n\n- Keep one well-commented base config (\u00a77) rather than retyping flags per command.\n- Use `--config-locations` profile files (\u00a77) for task-specific overrides (audio-only profile, archival/lossless profile, etc.) instead of one giant config with conflicting settings.\n\n### Updates\n\n- Update yt-dlp **before** any significant batch job \u2014 site extractors break often, and a stale version is the #1 cause of \"it randomly stopped working\" reports.\n- Automate the update as the first line of any scheduled script (\u00a717).\n\n### Security\n\n- Only download the `.exe` from the official `github.com/yt-dlp/yt-dlp` releases page (\u00a72); verify checksums.\n- Never share `cookies.txt` or a browser profile that has active login sessions.\n- Be cautious with random third-party \"yt-dlp GUI\" wrappers (\u00a724) \u2014 stick to actively maintained, source-available ones.\n\n### Privacy\n\n- `--cookies-from-browser` reads live session cookies \u2014 treat any exported `cookies.txt` file as sensitive as a password.\n- `--write-comments`/`--write-info-json` can capture other users' comment text/usernames \u2014 be mindful if you're archiving content for sharing elsewhere.\n\n### Responsible downloading\n\n- Respect `--sleep-interval`/rate limits on batch jobs rather than hammering a site as fast as technically possible (\u00a716, \u00a718) \u2014 this is both good etiquette and reduces your own odds of getting rate-limited or blocked.\n- Revisit \u00a71's legal/ToS considerations for anything beyond personal, fair-use archival of content you have rights to.\n\n---\n\n## 22. Frequently Used Commands (Cheat Sheet)\n\n| Goal | Command |\n|---|---|\n| Best quality video (any resolution) | `yt-dlp -f \"bv*+ba/b\" \"URL\"` |\n| Best quality, capped at 1080p, MKV | `yt-dlp -S \"res:1080,vcodec:h264,acodec:aac\" --merge-output-format mkv --remux-video mkv \"URL\"` |\n| Best quality, capped at 4K | `yt-dlp -f \"bv*[height<=2160]+ba/b[height<=2160]\" \"URL\"` |\n| Best quality audio, no re-encode overhead | `yt-dlp -x --audio-format opus --audio-quality 0 \"URL\"` |\n| Best quality audio, universal compatibility | `yt-dlp -x --audio-format mp3 --audio-quality 0 \"URL\"` |\n| Download an entire playlist | `yt-dlp \"PLAYLIST_URL\"` |\n| Download a whole channel | `yt-dlp \"https://www.youtube.com/@Channel/videos\"` |\n| Convert audio (any downloaded video \u2192 MP3) | `yt-dlp -x --audio-format mp3 \"URL\"` |\n| Embed thumbnail as cover art | `yt-dlp --embed-thumbnail \"URL\"` |\n| Download subtitles (manual, English) | `yt-dlp --write-subs --sub-langs en \"URL\"` |\n| Embed metadata + chapters | `yt-dlp --embed-metadata --embed-chapters \"URL\"` |\n| Use browser cookies | `yt-dlp --cookies-from-browser chrome \"URL\"` |\n| Mark SponsorBlock segments (non-destructive) | `yt-dlp --sponsorblock-mark all \"URL\"` |\n| Remove SponsorBlock segments (destructive) | `yt-dlp --sponsorblock-remove sponsor,selfpromo \"URL\"` |\n| Use a SOCKS5/HTTP proxy | `yt-dlp --proxy \"socks5://127.0.0.1:9050\" \"URL\"` |\n| Sync a channel, skip already-downloaded | `yt-dlp --download-archive archive.txt \"CHANNEL_URL\"` |\n| Custom output template | `yt-dlp -o \"%(uploader)s/%(title)s [%(id)s].%(ext)s\" \"URL\"` |\n| List available formats first | `yt-dlp -F \"URL\"` |\n| Update yt-dlp (standalone `.exe` only) | `yt-dlp -U` |\n\n---\n\n## 23. Version Differences\n\n### yt-dlp vs. youtube-dl\n\nyt-dlp is a youtube-dl fork based on the now-inactive youtube-dlc, focused on adding new features/patches while staying current with upstream youtube-dl. Practical differences that matter day-to-day:\n\n- **Format sorting**: yt-dlp changed the default sort so higher resolution/better codecs are preferred over raw bitrate, and added the `-S` flag for full custom control \u2014 youtube-dl's format selection is comparatively primitive.\n- **SponsorBlock** (\u00a715): yt-dlp-exclusive.\n- Release cadence: yt-dlp ships fixes within days of a site breaking; youtube-dl's development has been comparatively dormant.\n- **`--ignore-errors` is enabled by default** in yt-dlp (youtube-dl requires the flag explicitly) \u2014 use `--abort-on-error` or `--compat-options abort-on-error` to restore the old fail-fast behavior.\n- **Multi-stream merging behavior differs**: yt-dlp does not allow merging multiple audio/video streams into one file by default the way youtube-dlc did (since it conflicts with `-f bv*+ba`); use `--audio-multistreams`/`--video-multistreams`, or `--compat-options multistreams`, to re-enable it.\n- **Playlist metadata files**: yt-dlp writes the same thumbnail/description/infojson metadata for playlists as for individual videos by default; use `--no-write-playlist-metafiles` or `--compat-options no-playlist-metafiles` to revert to youtube-dl's behavior.\n- For full backward compatibility with youtube-dl's exact defaults across the board: `--compat-options all`.\n\n### Deprecated options & modern replacements\n\n| Deprecated / legacy | Modern replacement |\n|---|---|\n| `--write-annotations` (site no longer supports it) | n/a \u2014 removed, YouTube annotations don't exist anymore |\n| Manually specifying `--external-downloader aria2c` for HLS/DASH | Use `-N`/`--concurrent-fragments` \u2014 aria2c HLS/DASH support was removed for security reasons (CVE-2026-50574) |\n| Old `%()s`-style unsafe conversions in `--exec` | Use `%()q` \u2014 unsafe `%()s`-style conversions were restricted for security; numeric conversions are unaffected |\n| `youtube-dl`-style single quoting on Windows examples | Use double quotes on Windows \u2014 single quotes don't reliably work the same way in cmd.exe/PowerShell as on Unix shells |\n\n### Breaking / notable recent changes (as of mid-2026)\n\n- The minimum recommended Python version was raised to 3.11, since Python 3.10 reaches end-of-life in October 2026 \u2014 pip-install users on old Python should upgrade Python itself soon.\n- Official Windows release binaries will soon require Windows 10 or later (i.e., Windows 7/8.1 standalone `.exe` support is being phased out \u2014 irrelevant if you're already on Windows 10/11, as this guide assumes).\n- Aria2c HLS/DASH support removed (security fix) \u2014 see above.\n- `--write-link`-derived shortcut file output is now validated/sanitized against a command-injection vulnerability (CVE-2026-55404) \u2014 always keep yt-dlp updated rather than pinning an old version for \"stability.\"\n\n---\n\n## 24. GUI Alternatives\n\n*(For users who'd rather not use the command line at all)*\n\n| GUI | Platform | Status | Notes |\n|---|---|---|---|\n| **yt-dlg** | Windows/macOS/Linux | Community-maintained fork of the old `youtube-dl-gui` | Simple, lightweight, wraps yt-dlp directly; good for absolute beginners who just want point-and-click downloads |\n| **Stacher** | Windows/macOS/Linux | Actively maintained, Electron-based | Clean modern UI, queue management, format selection dropdowns; heavier resource footprint than a native app |\n| **Media Downloader (GPL)** | Windows/Linux (Flatpak on Linux) | Actively maintained | GTK-based, exposes most yt-dlp flags through checkboxes, good for users who want GUI *and* fine control |\n| **Parabolic** (formerly \"Video Downloader\") | Windows/Linux (also available via Microsoft Store on Windows) | Actively maintained | Modern Fluent-style UI on Windows, good playlist/batch support |\n\n**Comparison notes:**\n- All of the above are **wrappers around yt-dlp itself** \u2014 they don't reimplement extraction logic, so their reliability directly depends on how quickly they bundle yt-dlp updates. If a GUI stops working, check whether its *bundled* yt-dlp is outdated before assuming the tool is abandoned.\n- None of them expose 100% of yt-dlp's CLI surface (advanced `-S` sort strings, SponsorBlock category granularity, etc.) \u2014 power users doing anything beyond \"download this video/playlist at this quality\" will eventually hit the GUI's ceiling and need the CLI anyway.\n- **Recommended use case split**: GUI for occasional single-video downloads by non-technical users; CLI (this guide) for anything involving automation, batch jobs, precise format control, or SponsorBlock/subtitle/metadata customization.\n\nAlways verify current maintenance status before installing any of these \u2014 GUI wrapper projects come and go faster than yt-dlp itself; check the project's GitHub for recent commits before trusting it with your setup.\n\n---\n\n## 25. Appendix\n\n### Glossary\n\n| Term | Meaning |\n|---|---|\n| **Extractor** | The site-specific module yt-dlp uses to parse a given website and find downloadable media |\n| **DASH** | Dynamic Adaptive Streaming over HTTP \u2014 the technology behind separate video/audio streams on YouTube etc. |\n| **HLS** | HTTP Live Streaming \u2014 Apple's segmented streaming protocol, common for live streams |\n| **Remux** | Changing a file's container (e.g. MP4 \u2192 MKV) without re-encoding the actual video/audio data \u2014 fast, lossless |\n| **Recode/Transcode** | Actually re-encoding video/audio into a different codec \u2014 slow, and always introduces some quality loss (lossy re-encode) |\n| **Format sort (`-S`)** | yt-dlp's preference-ranking system for choosing among multiple available formats |\n| **Format selector (`-f`)** | The expression language for filtering/choosing specific formats |\n| **PO Token** | A YouTube anti-bot proof-of-origin token some clients require for certain streams \u2014 handled automatically by yt-dlp's JS-challenge solving when needed |\n\n### Common command reference (quick recall)\n\n```\n-F list formats\n-f SELECTOR choose format(s)\n-S SORT_STRING custom sort order\n-o TEMPLATE output filename template\n-P PATH output folder\n-x extract audio\n--audio-format FORMAT audio codec for -x\n--embed-metadata/-thumbnail/-chapters/-subs\n--sponsorblock-mark/-remove CATEGORIES\n--cookies-from-browser BROWSER\n--download-archive FILE\n--playlist-items RANGE\n-U self-update (standalone exe only)\n-v verbose (debugging)\n```\n\n### Useful links\n\n- Official repository: https://github.com/yt-dlp/yt-dlp\n- Official releases: https://github.com/yt-dlp/yt-dlp/releases\n- Official wiki: https://github.com/yt-dlp/yt-dlp/wiki\n- Official FFmpeg Windows builds: https://github.com/yt-dlp/FFmpeg-Builds\n- FFmpeg project documentation: https://ffmpeg.org/documentation.html\n- SponsorBlock project: https://sponsor.ajay.app/\n- yt-dlp Wiki \u2014 Installation: https://github.com/yt-dlp/yt-dlp/wiki/Installation\n\n### Trusted community resources\n\n- GitHub Issues (`yt-dlp/yt-dlp/issues`) \u2014 the best place to check for currently-known, actively-tracked bugs before assuming your own setup is broken.\n- `r/DataHoarder` and `r/youtubedl` on Reddit \u2014 active communities for archival/automation workflows.\n- Official Discord (linked from the GitHub repo) \u2014 real-time help from maintainers and power users.\n\n---\n\n*This guide reflects yt-dlp `2026.07.04` and the state of the official documentation as of July 2026. yt-dlp updates frequently \u2014 run `yt-dlp --help` and check the release notes at the link above for anything that may have changed since.*\n", "creation_timestamp": "2026-07-14T08:07:20.031625Z"} https://vulnerability.circl.lu/sighting/3d2fd8e2-1d31-418a-9117-81b5a3a37f36/export Tue, 14 Jul 2026 08:07:20 +0000 https://vulnerability.circl.lu/sighting/0a758347-1334-4fb3-8e22-0e665ae4ec02/export {"uuid": "0a758347-1334-4fb3-8e22-0e665ae4ec02", "vulnerability_lookup_origin": "1a89b78e-f703-45f3-bb86-59eb712668bd", "author": "9f56dd64-161d-43a6-b9c3-555944290a09", "vulnerability": "CVE-2026-55404", "type": "seen", "source": "https://bsky.app/profile/kriptabiz.bsky.social/post/3mqktfz7kmj2d", "content": "\u0423\u044f\u0437\u0432\u0438\u043c\u043e\u0441\u0442\u044c CVE-2026-55404 \u0432 yt-dlp \u0438 youtube-dl: \u0443\u0433\u0440\u043e\u0437\u0430 \u0431\u0435\u0437\u043e\u043f\u0430\u0441\u043d\u043e\u0441\u0442\u0438 \u0438 \u0441\u043f\u043e\u0441\u043e\u0431\u044b \u0437\u0430\u0449\u0438\u0442\u044b\n\n\n\nhttps://kripta.biz/posts/4DF505C7-5C54-475F-B261-B67AF169DD04", "creation_timestamp": "2026-07-13T23:21:03.233601Z"} {"uuid": "0a758347-1334-4fb3-8e22-0e665ae4ec02", "vulnerability_lookup_origin": "1a89b78e-f703-45f3-bb86-59eb712668bd", "author": "9f56dd64-161d-43a6-b9c3-555944290a09", "vulnerability": "CVE-2026-55404", "type": "seen", "source": "https://bsky.app/profile/kriptabiz.bsky.social/post/3mqktfz7kmj2d", "content": "\u0423\u044f\u0437\u0432\u0438\u043c\u043e\u0441\u0442\u044c CVE-2026-55404 \u0432 yt-dlp \u0438 youtube-dl: \u0443\u0433\u0440\u043e\u0437\u0430 \u0431\u0435\u0437\u043e\u043f\u0430\u0441\u043d\u043e\u0441\u0442\u0438 \u0438 \u0441\u043f\u043e\u0441\u043e\u0431\u044b \u0437\u0430\u0449\u0438\u0442\u044b\n\n\n\nhttps://kripta.biz/posts/4DF505C7-5C54-475F-B261-B67AF169DD04", "creation_timestamp": "2026-07-13T23:21:03.233601Z"} https://vulnerability.circl.lu/sighting/0a758347-1334-4fb3-8e22-0e665ae4ec02/export Mon, 13 Jul 2026 23:21:03 +0000