Skip to content

Start typing. Errors match on their exact yt-dlp output.

↑ ↓ to move, ↵ to open esc to close

Download and Embed Subtitles with yt-dlp

Tested on yt-dlp 2026.07.28 Updated

Quick answer

Real subtitles and machine captions are two different things with two different flags, and asking for the first alone is why --write-subs so often produces nothing. Ask for both:

both kinds, embedded in the file 
yt-dlp --write-subs --write-auto-subs --sub-langs "en.*" --embed-subs --merge-output-format mkv "URL"

Look before asking

bash 
yt-dlp --list-subs "URL"

The output separates two lists. Available subtitles are real ones, written or reviewed by the uploader. Available automatic captions are speech recognition — usually only in the video's spoken language, plus machine translations of it.

Most videos have no real subtitles at all. That single fact explains nearly every "subtitles do not work" report:

FlagGets
--write-subsUploader-provided only — often nothing
--write-auto-subsMachine captions
BothReal ones where they exist, machine ones otherwise

Choosing languages

bash 
yt-dlp --write-subs --sub-langs "en" "URL"
yt-dlp --write-subs --sub-langs "en.*" "URL"          # en, en-US, en-GB, en-orig
yt-dlp --write-subs --sub-langs "en,es,fr" "URL"
yt-dlp --write-subs --sub-langs "all" "URL"
yt-dlp --write-subs --sub-langs "all,-live_chat" "URL"

Use en.* rather than en. YouTube tags auto-captions with a region or with -orig, and the plain form quietly misses them.

all on a popular video means a hundred machine translations, most of them useless. -live_chat excludes the chat replay, which is not a subtitle track and is often enormous.

Embedded or separate

Embedded travels with the file and works on a TV or a phone. Separate is editable and readable as text:

embedded, in mkv 
yt-dlp --write-subs --write-auto-subs --sub-langs "en.*" --embed-subs --merge-output-format mkv "URL"
separate .srt files 
yt-dlp --write-subs --write-auto-subs --sub-langs "en.*" --convert-subs srt "URL"

Formats

YouTube serves VTT. Plenty of players read only SRT, which is why converting is usually worth doing even when you are keeping the file separate:

bash 
yt-dlp --write-subs --convert-subs srt "URL"

Available targets: srt, ass, vtt, lrc. lrc is for synchronised lyrics, which is a genuinely nice use of auto-captions on a music video.

Subtitles without the video

Useful for transcripts, search, or feeding text to something else:

bash 
yt-dlp --skip-download --write-subs --write-auto-subs --sub-langs "en.*" --convert-subs srt "URL"

Across a whole channel, that produces a searchable text archive of everything ever said on it — which is a small amount of work for a surprisingly useful thing:

bash 
yt-dlp --skip-download --write-auto-subs --sub-langs "en.*" --convert-subs srt \
  --download-archive subs.txt -i \
  -o "%(upload_date>%Y-%m-%d)s - %(title)s.%(ext)s" \
  "CHANNEL_URL"

Burning subtitles into the picture

yt-dlp will not do this — it means re-encoding the video, which is outside what a downloader should do silently. Two steps:

bash 
yt-dlp --write-subs --write-auto-subs --sub-langs "en.*" --convert-subs srt -o "video.%(ext)s" "URL"
ffmpeg -i video.mp4 -vf "subtitles=video.en.srt" -c:a copy video-subbed.mp4

Slow, lossy, and irreversible — but the only option for a player that cannot render subtitles at all.

A config for subtitles

yt-dlp.conf 
--write-subs
--write-auto-subs
--sub-langs en.*,-live_chat
--embed-subs
--convert-subs srt
--merge-output-format mkv

Add these to your config file if you always want subtitles. Note the mkv line — without it, embedding fails on any video whose subtitles arrive as VTT.

If it fails

  • Nothing downloads. Missing --write-auto-subs. Check --list-subs first.
  • Downloads, but the player ignores them. VTT. Add --convert-subs srt.
  • Embedding fails. mp4 refusing the format. Use mkv, or convert to srt first.
  • Subtitles drift out of sync. Usually a variable-frame-rate source rather than a subtitle problem. Remuxing to mkv often fixes it: --remux-video mkv.
  • Empty .srt files. The auto-captions were still being generated. Retry in an hour — YouTube produces them asynchronously after upload.

Frequently asked

Why did --write-subs produce nothing?
Because most videos have no uploader-provided subtitles at all — only YouTube's machine captions, which are a separate thing. Add --write-auto-subs and they appear.
What is the difference between --sub-langs en and en.*?
en matches exactly that tag. en.* also matches en-US, en-GB and en-orig. On YouTube the auto-captions are frequently tagged with a region, so the plain form misses them.
Why will my player not show the subtitles?
YouTube serves VTT, and plenty of players only read SRT. --convert-subs srt fixes it. If they are embedded in an mp4, that container is also fussy — mkv is not.
How do I burn subtitles into the picture?
yt-dlp cannot, because that means re-encoding the video. Download the SRT, then use ffmpeg with the subtitles filter — the command is on this page.

Related