Spoiler: |
In our present volatile state of the internet, the impermanence of media is a concern, particularly that of rare materials. Inevitably, platforms/websites collapse, licenses expire, legal action is taken, people take down their own libraries of uploads after "cold feet" (no blame, just the facts). For those who preserve resources/entertainment, there exists an imperative to navigate the shifting sands of CDNs, DRM wrappers, obfuscated JS delivery mechanisms, and such.
For almost a decade, youtube-dl (now practically deprecated) served amongst the primary bearers for this task. However, as platform algorithms grew more complex and development slowed, an active fork was developed which significantly built upon the capabilities of CLI media extraction: yt-dlp.
yt-dlp is not simply a downloader, it's a sophisticated media processing framework - designed to address specific throttling issues introduced by YT but has expanded to include a massive suite of features: support for thousands of non-YT sites, integration with the SponsorBlock API, advanced format sorting, and plugin support. Unlike simple retrieval scripts, yt-dlp operates as a browser emulator, a network transport manager, and a multimedia post-processor altogether.
This post is intended to serve as a (mostly-)exhaustive technical manual for the tool at a practical level. Minimal prior knowledge is assumed for basic use cases and installation, but it is mainly intended for those comfortable with using software or even yt-dlp itself. Advanced sections will be recognizable for those who know what they're looking for, therefore I will not be breaking those down into ELI5 terms. If you are a total beginner, I would recommend the Stacher7 GUI instead: https://stacher.io/
1.1 The Architecture
To master yt-dlp, one must first understand its internal data flow, which operates in three phases. Understanding this pipeline is important for debugging and configuration, as command-line flags often target specific parts of this process. If you are not interested, skip to section 2.
- 1.1.1 The Extractor Phase
When a link is passed into yt-dlp, the extractor is the first component that is engaged. Its role is simply informational. The extractor processes the target webpage’s HTML (think of it as the basic design code), executes necessary JavaScript (via internal interpreters or external tools like PhantomJS), interprets embedded JSON blobs, and scrapes metadata (data about data).
Function: It builds an "Info Dict(ionary)" - a JSON object containing the video's title, uploader, upload date, and the list of available formats (meaning the video streams, audio streams, subtitles).
Variety: yt-dlp includes over 1,700 site-specific extractors. If a specific extractor does not exist, the generic extractor attempts to locate standard HTML <video> tags or m3u8 playlists (files that contain URLs to media resources). - 1.1.2 The Downloader Phase
Once the desired format is selected (based on your criteria), the downloader handles the transfer of binary data.
Native vs External: yt-dlp includes a native HTTP/HTTPS client. However, for complex streaming protocols like DASH (Dynamic Adaptive Streaming over HTTP) or HLS (HTTP Live Streaming), it can hand off the download task to external binaries like ffmpeg or aria2c to improve throughput or handle fragmented streams. - 1.1.3 The Post-Processing Phase
After the raw data is locally available, the post-processor starts. This is where yt-dlp differentiates itself from simple downloaders...
Merging: If HD video and audio were downloaded as separate files (a standard practice for modern streaming optimization), the standard FFmpegMerger combines them into a single container (like MKV).
Embedding: Metadata, thumbnails, subtitles, and chapters are injected into the file.
Modification: Tools like SponsorBlock can remove segments, or exec commands can trigger scripts to move or rename files.
The robustness of a yt-dlp installation depends on the environment in which it resides. While it is portable, the archival capabilities are quite compromised without its primary dependency: FFmpeg. Without FFmpeg, yt-dlp cannot merge separate video and audio streams, limiting downloads to legacy formats and preventing format conversion.
2.1 Windows Installation and Setup
Windows does not natively manage command-line dependencies with the ease of UNIX systems, making the setup process slightly more involved. The goal is to create a globally accessible environment where yt-dlp and ffmpeg can be conveniently invoked from any directory.
2.1.1 Method A: Package Managers
If you prefer automated updates and dependency management, third-party package managers would be the way to go.
- Winget: Native to modern Windows builds.
Installation (type "cmd" in your Windows search for the terminal): [Code] Maintenance: [Code] Should be noted that Winget configurations may sometimes lag behind the "nightly" releases required to bypass aggressive YT algorithm changes. - Scoop: May be preferred for user-space isolation.
Installation: [Code] - Scoop automatically handles the PATH linking (i.e the convenient invoke) for ffmpeg
Maintenance: [Code] - Chocolatey: Bit of a heavyweight, often used in corporate deployments.
Installation: [Code] Maintenance: [Code]
If you require a portable installation (meaning it can be thrown even on a USB stick) or specific version control, manual installation is the preferred method. Or if you just don't like package managers :p
Step 1: Directory prep
Do not run archival tools from the Downloads folder, it's a mess. Create a dedicated directory, something like [Code].
Step 2: Acquiring
Navigate to the Github releases page. Download yt-dlp.exe. This is a PyInstaller-frozen binary also containing the python interpreter and required libraries. Move it into your dedicated folder. Currently: https://github.com/yt-dlp/yt-dlp/releases/
Step 3: The FFmpeg Dependency
yt-dlp requires ffmpeg.exe and ffprobe.exe to be present in the system PATH or the same directory.
- Download from the yt-dlp/FFmpeg-Builds page (these builds are patched specifically to address bugs that affect yt-dlp, such as HLS stream concatenation).
- Extract ffmpeg.exe and ffprobe.exe straight into [Code].
To run yt-dlp from any location:
- Press Win + R, type [Code] and hit Enter.
- Navigate to the advanced tab and click Environment Variables.
- In "System variables", locate Path. Click edit.
- Click new and paste the path to your folder: [Code].
2.2 macOS Installation and Setup
MacOS offers a more streamlined path manipulation but introduces some security hurdles. Note that I no longer have a Mac, so this is off of memory and online tutorials.
2.2.1 Method A: Homebrew
Homebrew is the package manager of choice for macOS. If not present, install via terminal: [Code] [Code] Homebrew installs binaries to [Code] (on Apple Silicon M chips) or [Code] (Intel CPUs) and automatically handles configuration.
2.2.2 Method B: Manual Binary
Download yt-dlp_macos from Github. Move to the standard binary location: [Code] Gatekeeper Quarantine:
On first run, macOS may block the binary as "unverified". To bypass, remove the quarantine attribute via terminal: [Code] Alternatively, go to System Settings > Privacy & Security, scroll to the bottom, and click "Allow Anyway" for yt-dlp.
2.3 Linux Installation
Well, if you're a Linux user, I trust you know what to do
, but regardless... for most Linux distributions, you can fetch the latest release directly.
[Code]
Ensure Python and FFmpeg are installed via your package manager (e.g., [Code] or [Code]).2.4 Android Installation
For mobile archiving! Download "Termux" via F-Droid (Google Play version is deprecated) and enter the commands: [Code] (The last command is to allow saving files to [Code] - watch for the permission popup on your device).
2.5 Execution Fundamentals Once installed, yt-dlp is directed entirely through commands in the Command Prompt (CMD) or PowerShell. For users unfamiliar with CLIs, it is important adhere to specific syntax rules carefully to prevent parsing errors. It can get tedious.
As Night himself writes:
2.5.1 Basic Syntax Structure The standard format of a command involves invoking the exe, setting your options, and providing the target. [Code]Night457 wrote: Mon Dec 08, 2025 2:29 pm I am not particularly fond of Command line either because I have to type accurately!
- The Binary: Typing yt-dlp tells Windows to look in your system PATH for the executable.
- The Flags: Instructions like [Code] or [Code] tell the program how to download. These can be placed before or after the URL, though placing them before is standard convention.
- The URL: The target link copied from your browser.
- Always Quote URLs: URLs often contain ampersands (&), question marks, or equals signs. In CMD and PowerShell, these are reserved control characters. The Error: If you paste a playlist link like [Code] without quotes, the shell interprets & as "End of command" and cuts off the playlist ID. The Fix: Wrap the URL in double quotes: [Code]
- Spaces in Paths: If you use the [Code] flag to define a download path that contains spaces, you must use quotes. [Code]
- Changing Directories: Use the [Code] command. [Code]
- Changing Drives (CMD Specific): If your storage is on a different drive (e.g. D:), standard cd commands in CMD will not switch the drive letter automatically. Use the /d switch: [Code]
Typing complex flags for every download is inefficient. yt-dlp utilizes a configuration file system to maintain your user preferences. This allows the creation of a "default" behavior, for example, always downloading english subtitles and merging to matroska, while command-line overrides can still be used.
3.1 Configuration File Locations
yt-dlp scans specific locations for a config file. Command line arguments always take precedence.
- Windows (System): [Code]
- Windows (User): [Code]
- macOS (System): [Code]
- macOS (User): [Code] or [Code]
The config file is plain text. You may write ignored comments starting with "#". Below is a sample configuration profile.
[Code] 3.3 Profiles via aliasing
You can emulate profiles using aliases in your config file, allowing you to skip the long string of flags. [Code] Usage: [Code] 4. Authentication: Accessing Gated Content
As platforms tighten security, accessing content often requires authentication. This includes age-gated videos, premium content, and membership-only videos.
4.1 Cookies Passthrough
yt-dlp does not support username/password login for major sites due to 2FA or JS challenges. It relies on cookies from the browser where you are logged in.
4.1.1 Automatic Extraction
Syntax: [Code] (Supports: chrome, firefox, edge, opera, brave, vivaldi, safari).
The Browser Locking Constraint: Chromium-based browsers lock their SQLite cookie database while running. If you run the command while Chrome is open, it will fail.
Solution 1: Close the browser completely.
Solution 2: Use the yt-dlp-ChromeCookieUnlock plugin.
Solution 3: Log in via a secondary browser (like Edge) and use that for extraction while browsing on your primary.
Keyring/Encryption: On Linux/macOS, browsers encrypt cookies using the system keyring (Gnome Keyring, KWallet, macOS Keychain). yt-dlp attempts to access this. If it fails, it may ask for a password or require the secretstorage Python dependency.
4.1.2 Manual Import
Use a browser extension like "Get cookies.txt LOCALLY" to export a cookies.txt file.
Usage: [Code] Note: This file contains active session tokens. Don't share it.
4.2 Netrc
For sites supporting basic authentication, yt-dlp supports the .netrc standard ([Code] on Unix, [Code] on Windows).
Format: [Code].
Usage: [Code].
5. The Selector Engine
A single YT video may be available in thirty different streams. The Selector Engine determines which bits are downloaded and how they are assembled.
5.1 The Format Table
Run [Code] to see the available formats, including ID, Extension, Resolution, Codec (AV1, VP9, H.264...), and Bitrate.
- AV1 (av01): High efficiency, requires beefier hardware to decode.
- VP9 (vp9): Google's open standard for 4K.
- H.264 (avc1): Legacy standard nowadays, greater compatibility.
The flag -f accepts a string that defines the filtering logic.
5.2.1 The Default Behavior
If -f is omitted, yt-dlp defaults to bv*+ba/b
- bv*: Best Video (potentially no audio).
- ba: Best Audio (no video).
- +: Merge them.
- /: OR.
- b: Best single file (pre-merged, usually 720p).
5.2.2 Explicit Filtering
- By Extension: [Code] (Ensures an MP4 container without encoding).
- By Codec: [Code] (Forces H.264/AAC for legacy compatibility).
- Direct Logic: [Code]
Sorting tells yt-dlp how to define "best". The default order is: res, fps, codec, size, br, asr, proto, ext, hasaud, source, id.
- Prioritize Smallest Size: [Code] (The + indicates ascending order).
- Prioritize Codec: [Code]
- Prioritize Bitrate: [Code] (Total Bitrate).
- Prioritize Dimensions: [Code]
When archiving channels, you often only want content from a specific era.
- Exact Date: [Code]
- Before/After: [Code] or [Code]
- Relative: [Code]
Sometimes simple date/playlist checks aren't enough. The [Code] flag allows for regex and boolean logic against metadata fields.
- Avoid Shorts: [Code]
- Specific Content: [Code]
- Complex Logic: [Code] (Downloads only non-live videos longer than a minute with over 100 likes).
If you do not wish to download an entire playlist of 5,000 videos:
- Specific Range: [Code]
- Specific Items: [Code]
- Random: [Code] (Good for grabbing a random sample of a channel).
6.1 Basic Interpolation
Flag: [Code].
Example: [Code] 6.2 Advanced Formatting
- Numeric Padding: [Code] outputs like 001, 002.
- Length Truncation: [Code] limits title to 50 chars (important for Windows path limits).
- Date Formatting: [Code] converts raw 20230101 into 2023-01-01.
Syntax: [Code] Example: [Code] This handles both TV shows (printing S01E01) and movies (printing just the title) in the same config!
7. Post-Processing
7.1 Metadata & Subtitles
- [Code]: Injects Atom/Matroska tags.
- [Code]: Embeds the video thumbnail as the file icon
- [Code]: Modifies metadata before writing (e.g., [Code] to repair titles).
- [Code] / [Code]: Downloads subtitles.
- [Code]: Converts VTT/ASS formats to SRT for better TV compatibility.
- [Code]: For languages
- [Code]: Places subtitles in the container
- [Code]: Download AI subs
Interfaces with the crowdsourced database to deal with these pesky sponsored segments.
- Marking: [Code]. Adds chapters to the file timeline.
- Removal (Destructive): [Code]. Physically butchers the file.
- API Configuration: If the default API is down, use [Code].
Useful for music compilations or "Full Albums" uploaded as a single video. [Code] This utilizes FFmpeg to cut the video into multiple files based on the chapters provided in the YT time-bar. You must update your output template to handle this, otherwise, the files will overwrite each other: [Code] 8. Network Operations, Geo-Bypass, and Performance
8.1 Proxies and Geo-Restriction
- X-Forwarded-For: [Code] (Default). Attempts to fake the HTTP header X-Forwarded-For to look like a different IP. This rarely works on modern CDNs.
- SOCKS5: Recommended for full TCP tunneling (such as through Tor). [Code]
- Source Address: [Code] (Bind to a specific NIC).
- Rate Limit: [Code] (Cap speed to avoid detection).
- External Downloaders: For heavily fragmented streams (HLS/DASH), handing off to aria2c can utilize multiple connections per file. [Code]
- Sleep Intervals: [Code] prevents HTTP 429 (Too Many Requests) errors during playlist downloads.
- Sleep Requests: [Code] waits between HTTP requests (distinct from downloads) to mimic human behavior.
9.1 Download Archive [Code] Tracks downloaded video IDs. If an ID exists in this file, yt-dlp skips it.
9.2 The --exec flag
Runs external commands at various stages.
Example: [Code] (Moves the file to cloud storage immediately after download). Stages can be specified, e.g. [Code] or [Code].
9.3 Windows Batch Script Note
When using output templates in a Windows .bat file, you must escape percentage signs by doubling them, as I demonstrate: [Code] 10. Advanced Extraction
10.1 The Generic Extractor
Used for unsupported sites. It scans for HTML tags, OpenGraph metadata, or embedded iframes from supported sites. If this fails, use browser Devtools (Network Tab) to find the .m3u8 URL and pass that directly to yt-dlp.
10.2 Live Stream Archiving
- [Code]: (YT) downloads buffered data from the start of a live stream.
- [Code]: Polls a premiere URL until it goes live.
- [Code]: Forces the MPEG-TS container. It is important for live streams; if the connection drops, a TS file remains readable, whereas an MP4 often becomes corrupt.
For complex logic, embedding yt-dlp in Python is superior to calling it via subprocess.
11.1 Basic Implementation [Code] 11.2 Hooks and Loggers
You can intercept status updates to build progress bars or logging systems.
- Logger Class: Override debug, warning, error.
- Progress Hook: A callback function executed on every data chunk.
12. Troubleshooting and Diagnostics
There are a couple common issues that you may run into (by NO means exhaustive!)
- Verbose Mode: [Code]. Firstly, very helpful for debugging. Essentially prints logs of what is happening (System Info, Config, Args, and Network Headers).
- The "Dry Run" (Simulation): [Code] (lowercase s). This simulates the download without fetching the binary data. Crucial for testing your [Code] or regex logic to ensure you aren't about to download 400 unwanted videos.
- Update the Binary: [Code]. If downloads suddenly break, YT likely updated their code. Run this to fetch the latest yt-dlp patch.
- 403 Forbidden: Often anti-bot protection. Refer to the cookies section from earlier.
- Sign in to confirm...: Age-gated content. Solution: Use Cookies.
- HTTP 429: Rate limit. Stop downloading, change IP, or use [Code].
- Glitchy Audio/Video: Ensure FFmpeg is up to date. Try toggling [Code] vs [Code].
- Filename too long: Use template slicing [Code] to respect the Windows limit.
