yt-dlp cheat sheet
Summary
This yt-dlp cheat sheet explains command-line options for downloading video, audio, subtitles, playlists, and livestreams, plus format control, cookies, and proxy use. Includes a comprehensive yt-dlp command reference table.
Introduction #
yt-dlp is a command-line tool based on youtube-dl that downloads videos and audio from websites such as YouTube, Vimeo, and hundreds more. It includes features such as automatic format selection, embedded subtitles, audio extraction, metadata embedding, cookie-based authentication, and segmented livestream handling.
Downloading #
Basic download #
yt-dlp https://www.example.com/watch?v=example
Downloads the best available audio and video, and merges them into one file using FFmpeg.
Download entire playlist #
yt-dlp -o "%(playlist_index)s - %(title)s.%(ext)s" https://www.example.com/playlist?list=example
Downloads each item in the playlist and names it using its position and title.
Batch download from file #
yt-dlp -a urls.txt
Reads and downloads all URLs listed in urls.txt. Each URL must be on its own line.
Download only new videos from a playlist #
yt-dlp --download-archive archive.txt --no-overwrites "PLAYLIST_URL"
Skips videos that were already downloaded. Video IDs are stored in archive.txt.
Download shorts or clips without full playlist #
yt-dlp --no-playlist "SHORTS_URL"
Prevents yt-dlp from treating shorts or clips as part of an associated playlist.
Download livestream #
yt-dlp --hls-use-mpegts https://www.example.com/watch?v=live_id
Downloads an HLS livestream using MPEG-TS format. This prevents corruption if interrupted.
Audio and subtitle handling #
Download only audio #
yt-dlp -x --audio-format mp3 https://www.example.com/watch?v=example
Extracts audio and converts it to MP3. Requires FFmpeg.
Extract audio without re-encoding #
yt-dlp -x --audio-format best --no-keep-video "URL"
Extracts the best audio stream without re-encoding. Original audio format is preserved.
Download subtitles with video #
yt-dlp --write-subs --sub-lang en --embed-subs https://www.example.com/watch?v=example
Downloads English subtitles and embeds them into the video file.
Download chapters as separate files #
yt-dlp --split-chapters "URL" -o "%(title)s - %(chapter)s.%(ext)s"
Splits a video by its chapter markers and saves each chapter as a separate file. Requires FFmpeg.
Format selection #
Specify format manually #
yt-dlp -f "bv*+ba" https://www.example.com/watch?v=example
Selects best video (bv) and best audio (ba) streams for merging.
Common format selection examples #
yt-dlp -f "best[height<=720]" "URL"
Downloads the best format with resolution 720p or lower.
yt-dlp -f "mp4" "URL"
Prefers formats in the MP4 container.
yt-dlp -f "bv[ext=webm]+ba[ext=m4a]" "URL"
Chooses specific video and audio stream extensions.
Output naming and file handling #
Set custom output filename #
yt-dlp -o "~/Videos/%(title)s.%(ext)s" https://www.example.com/watch?v=example
Use more template variables #
yt-dlp -o "%(upload_date>%Y-%m-%d)s - %(title)s.%(ext)s" "URL"
This example uses the upload_date field formatted as YYYY-MM-DD.
Avoid temporary or partial files #
yt-dlp --no-part --no-continue https://www.example.com/watch?v=example
Disables creation of .part files and disables resuming.
Split into chapters #
yt-dlp --split-chapters -o "%(title)s - %(chapter)s.%(ext)s" "URL"
Creates separate output files for each chapter using the chapter title.
Metadata and thumbnails #
Embed metadata and thumbnail #
yt-dlp --embed-metadata --embed-thumbnail https://www.example.com/watch?v=example
Adds video metadata and thumbnail image into the output file.
Download livestream chat #
yt-dlp --write-chat "LIVE_URL"
Saves live chat messages as a .json file. Only works for platforms that support chat.
Authentication and cookies #
Use cookies from file #
yt-dlp --cookies cookies.txt https://www.example.com/watch?v=restricted
Use browser cookies directly #
yt-dlp --cookies-from-browser firefox "URL"
Extracts cookies directly from Firefox. Also supports Chrome and Chromium.
Network and performance #
Use a proxy #
yt-dlp --proxy socks5://127.0.0.1:9050 https://www.example.com/watch?v=example
Add custom HTTP headers #
yt-dlp --add-header "User-Agent: CustomAgent/1.0" https://example.com/video
Use external downloader #
yt-dlp --external-downloader aria2c --external-downloader-args "-x 16 -k 1M" https://www.example.com/watch?v=example
Limit download speed #
yt-dlp --limit-rate 500K https://www.example.com/watch?v=example
Limits bandwidth usage to 500 kilobytes per second.
Add random delays to avoid bans #
yt-dlp --sleep-interval 5 --max-sleep-interval 10 "URL"
Introduces a random delay between downloads from 5 to 10 seconds.
Advanced features #
Re-encode to a different format #
yt-dlp --recode-video mp4 https://www.example.com/watch?v=example
Re-encodes the video to MP4 format using FFmpeg after download.
Use configuration file #
Example file: ~/.config/yt-dlp/config
--format bv*+ba
--merge-output-format mp4
--embed-thumbnail
--embed-metadata
--write-subs
--sub-lang en
--output ~/Videos/%(title)s.%(ext)s
This file is read automatically if placed in the default location or specified with --config-location.
Troubleshooting and maintenance #
Skip errors and continue #
yt-dlp --ignore-errors "URL"
Skips videos that fail to download and continues with the next.
Bypass SSL certificate issues #
yt-dlp --no-check-certificate "URL"
Ignores invalid SSL certificates. This is insecure and should be avoided unless necessary.
Show detailed output for debugging #
yt-dlp --verbose "URL"
Prints verbose logs for debugging purposes.
Update yt-dlp to latest version #
yt-dlp -U
Checks for and installs the latest available version of yt-dlp.
Command reference table #
| Command | Description |
|---|---|
yt-dlp URL | Downloads the best available video and audio. |
yt-dlp -x --audio-format mp3 URL | Extracts audio and converts it to MP3 using FFmpeg. |
yt-dlp -x --audio-format best --no-keep-video URL | Extracts audio without re-encoding and deletes the video. |
yt-dlp --write-subs --sub-lang en --embed-subs URL | Downloads and embeds English subtitles into the video. |
yt-dlp --write-auto-subs URL | Downloads automatically generated subtitles. |
yt-dlp -f "bv*+ba" URL | Downloads best video and best audio and merges them. |
yt-dlp -F URL | Lists all available video and audio formats. |
yt-dlp -f "best[height<=720]" URL | Selects the best video with height 720p or lower. |
yt-dlp -f "mp4" URL | Chooses formats in the MP4 container. |
yt-dlp -f "bv[ext=webm]+ba[ext=m4a]" URL | Selects specific formats for video and audio. |
yt-dlp -o "~/Videos/%(title)s.%(ext)s" URL | Sets a custom output filename and directory. |
yt-dlp -o "%(upload_date>%Y-%m-%d)s - %(title)s.%(ext)s" URL | Uses upload date and title in the filename. |
yt-dlp -o "%(playlist_index)s - %(title)s.%(ext)s" PLAYLIST_URL | Downloads a playlist with indexed filenames. |
yt-dlp --split-chapters -o "%(title)s - %(chapter)s.%(ext)s" URL | Downloads each chapter as a separate file. |
yt-dlp -a urls.txt | Downloads all URLs listed in the urls.txt file. |
yt-dlp --download-archive archive.txt --no-overwrites PLAYLIST_URL | Skips videos already downloaded and logs them to archive.txt. |
yt-dlp --no-playlist SHORTS_URL | Avoids downloading full playlist when URL is a short or clip. |
yt-dlp --no-part --no-continue URL | Disables .part file and disables resuming of downloads. |
yt-dlp --embed-metadata --embed-thumbnail URL | Embeds metadata and thumbnail into the downloaded file. |
yt-dlp --write-chat URL | Downloads livestream chat messages as JSON. |
yt-dlp --cookies cookies.txt URL | Uses a cookie file for access-restricted content. |
yt-dlp --cookies-from-browser firefox URL | Extracts cookies directly from Firefox. |
yt-dlp --proxy socks5://127.0.0.1:9050 URL | Downloads via a SOCKS5 proxy. |
yt-dlp --add-header "User-Agent: CustomAgent/1.0" URL | Sends a custom HTTP header. |
yt-dlp --external-downloader aria2c --external-downloader-args "-x 16 -k 1M" URL | Uses aria2c for parallel segment downloading. |
yt-dlp --limit-rate 500K URL | Limits download speed to 500 KB/s. |
yt-dlp --sleep-interval 5 --max-sleep-interval 10 URL | Adds random sleep interval between downloads. |
yt-dlp --hls-use-mpegts URL | Downloads HLS livestream using MPEG-TS for resilience. |
yt-dlp --recode-video mp4 URL | Re-encodes downloaded file to MP4 using FFmpeg. |
yt-dlp --ignore-errors URL | Skips errors and continues with remaining downloads. |
yt-dlp --no-check-certificate URL | Disables SSL certificate verification (not secure). |
yt-dlp --verbose URL | Shows detailed log output for debugging. |
yt-dlp -U | Updates yt-dlp to the latest available version. |
FAQ's #
Most common questions and brief, easy-to-understand answers on the topic:
Can yt-dlp download private or age-restricted videos?
Yes, yt-dlp can download these videos if you provide a valid cookie file using the --cookies option.
Does yt-dlp work with streaming playlists like M3U8?
Yes, yt-dlp supports M3U8 and other streaming formats, and can download them using segment stitching.
How can I resume an interrupted download?
Use the --no-part option to prevent partial file cleanup. yt-dlp resumes if the server supports byte ranges.
Is ffmpeg required for audio or format conversion?
Yes, yt-dlp relies on ffmpeg for merging formats, extracting audio, and applying re-encodings.
What websites are supported by yt-dlp?
yt-dlp supports over 1,000 websites including YouTube, Vimeo, Dailymotion, and many regional, or livestreaming platforms.
Further readings #
Sources and recommended, further resources on the topic:
- GitHub: yt-dlp repository
- GitHub: yt-dlp README with options and usage
- Arch Linux: yt-dlp manual page
- FFmpeg: Official site
- yt-dlp: List of supported sites
Author
Jonas Jared Jacek (J15k)
Jonas works as project manager, web designer, and web developer since 2001. On top of that, he is a Linux system administrator with a broad interest in things related to programming, architecture, and design. See: https://www.j15k.com/License
yt-dlp cheat sheet by Jonas Jared Jacek is licensed under CC BY-SA 4.0.
This license requires that reusers give credit to the creator. It allows reusers to distribute, remix, adapt, and build upon the material in any medium or format, for noncommercial purposes only. To give credit, provide a link back to the original source, the author, and the license e.g. like this:
<p xmlns:cc="http://creativecommons.org/ns#" xmlns:dct="http://purl.org/dc/terms/"><a property="dct:title" rel="cc:attributionURL" href="https://www.ditig.com/yt-dlp-cheat-sheet">yt-dlp cheat sheet</a> by <a rel="cc:attributionURL dct:creator" property="cc:attributionName" href="https://www.j15k.com/">Jonas Jared Jacek</a> is licensed under <a href="https://creativecommons.org/licenses/by-sa/4.0/" target="_blank" rel="license noopener noreferrer">CC BY-SA 4.0</a>.</p>For more information see the Ditig legal page.
