How to set a custom output filename in yt-dlp
Summary
This guide explains how to use yt-dlp's output template feature to create custom filenames for your downloads. You will learn about placeholders, organizing files into folders, and setting a default template.
Introduction #
By default, yt-dlp saves files using the video title. You can control the exact filename and folder structure using, what yt-dlp calls output templates.
Also check out our yt-dlp cheat sheet.
The core -o option #
The primary method for setting a custom filename is the -o (or --output) option. You provide a template string that yt-dlp fills with information from the video.
yt-dlp -o "custom_name.%(ext)s" "https://www.example.com/watch?v=VIDEO_ID"
Output template placeholders #
Placeholders are variables that yt-dlp replaces with actual metadata. You combine them to build your desired filename.
| Placeholder | Description |
|---|---|
%(title)s | The full title of the video. |
%(ext)s | The file extension (e.g., mp4, webm, m4a). |
%(uploader)s | The name of the channel or uploader. |
%(upload_date)s | The upload date in YYYYMMDD format. |
%(id)s | The unique video ID. |
%(playlist_title)s | The title of the playlist, if applicable. |
%(playlist_index)s | The video’s position in the playlist, padded with zeros. |
Output template examples #
These examples show practical uses of the output template.
Include the uploader’s name #
yt-dlp -o "%(uploader)s - %(title)s.%(ext)s" "URL"
This creates a filename like ChannelName - Video Title.mp4.
Organize files into folders by uploader #
yt-dlp -o "%(uploader)s/%(title)s.%(ext)s" "URL"
yt-dlp will create a folder named after the uploader and save the video inside it.
Structure playlist downloads #
yt-dlp -o "%(playlist_title)s/%(playlist_index)s - %(title)s.%(ext)s" "PLAYLIST_URL"
This creates a main folder for the playlist, with each file numbered (e.g., 001 - Song Name.mp4).
Use a date-first format for sorting #
yt-dlp -o "%(upload_date)s - %(title)s.%(ext)s" "URL"
This results in filenames like 20231015 - Video Title.mp4, which sort chronologically.
Set a default output template #
You can configure a default output template in the yt-dlp configuration file so you do not have to specify it for every download.
Location of the yt-dlp configuration file: On Linux and macOS you can find the file in ~/.config/yt-dlp/config. On Windows the files resides in %APPDATA%/yt-dlp/config.txt.
Add a line to the file with your preferred template, e.g.:
# Save all files in a Downloads/yt-dlp folder, organized by uploader
-o "~/Downloads/yt-dlp/%(uploader)s/%(title)s.%(ext)s"
Handle problematic characters #
Some video titles contain characters that are invalid in filenames, such as /, :, or ?. Using the --restrict-filenames flag will replace these characters with underscores.
yt-dlp --restrict-filenames -o "%(title)s.%(ext)s" "URL"
Prevent overwriting existing files #
The --no-overwrites option tells yt-dlp to skip downloading a file if a file with the same name already exists. This is useful for resuming interrupted playlist downloads.
yt-dlp --no-overwrites -o "your_template" "URL"
FAQ's #
Most common questions and brief, easy-to-understand answers on the topic:
What is the most basic output template for a single video?
The most basic template is -o "%(title)s.%(ext)s". This saves the file using the video's full title and correct file extension.
How do you organize playlist downloads into folders?
Use a template like -o "%(playlist_title)s/%(playlist_index)s - %(title)s.%(ext)s". This creates a folder named after the playlist and numbers each file.
Where can you set a default output template?
You can set a default template in the yt-dlp configuration file. On Linux and macOS, this file is located at ~/.config/yt-dlp/config.
What should you do if you get a 'invalid character in filename' error?
Use the --restrict-filenames option. This replaces problematic characters like slashes or colons with underscores.
Further readings #
Sources and recommended, further resources on the topic:
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
How to set a custom output filename in yt-dlp 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/set-yt-dlp-output-filename">How to set a custom output filename in yt-dlp</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.
