ytdlp.org

Practical yt-dlp docs: install, commands, fixes, cookies, and workflows.

Current section

How-to

Embed thumbnails and metadata with yt-dlp

By default yt-dlp saves the media and nothing else: no cover art, no title or artist tags. Two options fix that, and a third lets you keep the thumbnail as its own image.

Quick answer

# video with cover art and tags
yt-dlp --embed-thumbnail --embed-metadata "<URL>"

# MP3 with cover art and tags
yt-dlp -x --audio-format mp3 --embed-thumbnail --embed-metadata "<URL>"

Both need ffmpeg. If yt-dlp stops with "Supported filetypes for thumbnail embedding are...", jump to the webm fix.

What you get

We tested on the Internet Archive's copy of Big Buck Bunny with yt-dlp 2026.10.26 in November 2026, using its MP4 format:

yt-dlp -f "b[ext=mp4]" --embed-thumbnail --embed-metadata \
  -o "thumb.%(ext)s" "https://archive.org/details/BigBuckBunny_124"

[info] Writing video thumbnail ... to: thumb.jpg
[Metadata] Adding metadata to "thumb.mp4"
[EmbedThumbnail] Neither mutagen nor AtomicParsley was found. Falling back to ffmpeg
[EmbedThumbnail] ffmpeg: Adding thumbnail to "thumb.mp4"

ffprobe thumb.mp4 then shows a third stream (an mjpeg image, the cover art) next to the video and audio, and tags for title, artist, date, description and the source URL in the comment field. The separate thumb.jpgis deleted once it's embedded. The "Neither mutagen nor AtomicParsley" line is a notice, not an error: ffmpeg did the job.

The MP3 command gave an MP3 with the same cover image and title and artist tags, which is what music players show. More on audio in extracting audio as MP3.

"Supported filetypes for thumbnail embedding"

yt-dlp can't embed cover art in every container. With the Ogg video (.ogv) format of the same file, it stopped with:

ERROR: Postprocessing: Supported filetypes for thumbnail embedding are: mp3, mkv/mka, ogg/opus/flac, m4a/mp4/m4v/mov

The same happens with webm, which is what YouTube's best video often comes as. Two fixes:

# keep the same streams, put them in an MKV (no re-encoding)
yt-dlp --remux-video mkv --embed-thumbnail "<URL>"

# or ask for formats that end up as MP4
yt-dlp -f "bv*[ext=mp4]+ba[ext=m4a]/b[ext=mp4]" --embed-thumbnail "<URL>"

The remux worked on our test: the MKV came out with the thumbnail attached as cover.jpg. The second command trades some quality options for an MP4; the format selection guide explains the selector.

Save the thumbnail as an image

# thumbnail only, no video, converted to PNG
yt-dlp --skip-download --write-thumbnail --convert-thumbnails png "<URL>"

# see every thumbnail size the site offers
yt-dlp --list-thumbnails "<URL>"

The first command wrote a single PNG next to where the video would have gone, named by your output template. Use --write-thumbnail together with --embed-thumbnail if you want the cover art inside the file and a copy on disk.

Set your own tags

--embed-metadata writes whatever yt-dlp knows. To change a field first, use --parse-metadata FROM:TO. FROM can be a field or fixed text:

# fixed artist
yt-dlp --parse-metadata "Blender Foundation:%(artist)s" --embed-metadata "<URL>"

# split "Artist - Song" titles into artist and title
yt-dlp -x --audio-format mp3 \
  --parse-metadata "title:%(artist)s - %(title)s" --embed-metadata "<URL>"

The first one printed [MetadataParser] Parsed artist from 'Blender Foundation': 'Blender Foundation' and the file's artist tag changed to match. The second only takes effect when the title has that shape; otherwise yt-dlp prints Could not interpret 'title' as '%(artist)s - %(title)s' and keeps the original tags, which is what happened on our test file.

Delivery

Want files delivered clean, not cleaned up after?

Paste a link to see the structured metadata a media-import API returns before delivery to S3 or a webhook.

Building this into an app? See the API your backend calls instead

Frequently asked questions

How do I embed the thumbnail in a yt-dlp download?

Add --embed-thumbnail: yt-dlp --embed-thumbnail "URL". It downloads the thumbnail, adds it to the file as cover art and deletes the image afterwards. It works for mp3, mkv/mka, ogg/opus/flac and m4a/mp4/m4v/mov files.

Why does yt-dlp say thumbnail embedding isn't supported?

yt-dlp can't embed cover art in some containers, webm and ogv among them, and stops with "Supported filetypes for thumbnail embedding are: mp3, mkv/mka, ogg/opus/flac, m4a/mp4/m4v/mov". Add --remux-video mkv (or pick an mp4 format) and run it again.

How do I save the thumbnail as a separate image?

Use --write-thumbnail. Add --skip-download if you only want the image, and --convert-thumbnails png (or jpg) to change its format.

What does --embed-metadata add?

Tags such as title, artist (taken from the uploader), date, description and the source URL, written into the file so music players and file managers can show them. --add-metadata is an alias for the same option.

Do I need mutagen or AtomicParsley?

No. yt-dlp uses mutagen or AtomicParsley when they're installed and otherwise falls back to ffmpeg, which worked in our tests. You do need ffmpeg.

Straightforward yt-dlp help for installs, commands, fixes, cookies, and repeatable workflows.

ytdlp.org is an independent, community-maintained documentation site. It is not affiliated with the yt-dlp project — the official source code lives at github.com/yt-dlp/yt-dlp.