ytdlp.org

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

Current section

How-to

Skip already-downloaded videos with yt-dlp --download-archive

If you run yt-dlp on the same channel or playlist again and again, you want it to fetch only what's new. An archive file does that: yt-dlp records every video it finishes and skips those on the next run.

Quick answer

yt-dlp --download-archive archive.txt "<PLAYLIST OR CHANNEL URL>"

Run the same command every time with the same archive.txt. yt-dlp creates the file on the first run. It checks video IDs, not file names, so moving or renaming downloads doesn't make it fetch them again.

What a rerun looks like

We tested with a public SoundCloud set and yt-dlp 2026.10.26 in November 2026. First run, two tracks:

yt-dlp --playlist-items 1:2 --download-archive sc.txt \
  -o "%(title)s.%(ext)s" "https://soundcloud.com/forss/sets/soulhack"

$ cat sc.txt
soundcloud 290
soundcloud 291

Each line is the extractor and the video's ID. Then three tracks, same archive:

yt-dlp --playlist-items 1:3 --download-archive sc.txt \
  -o "%(title)s.%(ext)s" "https://soundcloud.com/forss/sets/soulhack"

[download] 290: has already been recorded in the archive
[download] 291: has already been recorded in the archive
[download] Destination: Funk for Nerds.m4a
[download] Finished downloading playlist: Soulhack

Only the new track was downloaded. A video is only written to the archive once it finishes, so a run that fails halfway retries that video next time.

Stop early on big channels: --break-on-existing

The archive skips downloads, but yt-dlp still walks the whole listing to check every entry. On a channel with thousands of videos, that's slow and a lot of requests. Since channels list newest first, you can stop at the first video you already have:

yt-dlp --download-archive archive.txt --break-on-existing "<CHANNEL URL>"

The catch: on a playlist listed oldest first, the first entry is one you already have, so it stops at once. That's what happened on our SoundCloud set:

[download] 290: has already been recorded in the archive
[info] Encountered a video that is already in the archive, stopping due to --break-on-existing
Aborting remaining downloads

Use it for channels and feeds, not for playlists that grow at the end. If you pass several URLs (or a batch file), add --break-per-input so a stop on one source moves on to the next instead of ending the whole run. We checked with a two-line batch file: yt-dlp stopped on the SoundCloud set and went on to the Internet Archive video.

Already have the files? Seed the archive

If you downloaded a channel before you started using an archive, record what's there without downloading it again:

yt-dlp --skip-download --force-write-archive \
  --download-archive archive.txt "<URL>"

On an Internet Archive video this wrote archiveorg BigBuckBunny_124 to a fresh file and downloaded nothing. Run it on the same URL you downloaded from, then switch to the normal command. Because the file is plain text, you can also delete a line to make yt-dlp download that video again, or concatenate two archives.

A command for a scheduled sync

yt-dlp --ignore-config \
  --download-archive /data/archive.txt \
  --break-on-existing --break-per-input \
  -o "/data/%(uploader)s/%(upload_date)s - %(title)s.%(ext)s" \
  -a channels.txt

Use an absolute path for the archive, since cron and systemd don't run from your home folder, and --ignore-config so a stray config file can't change what the job does. Scheduling itself is covered in automating yt-dlp.

Recurring sources

Pulling from the same sources on repeat?

Paste a link to preview what a maintained import API returns for it — across 1,000+ sites.

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

Frequently asked questions

How do I make yt-dlp skip videos I already downloaded?

Add --download-archive with a file name: yt-dlp --download-archive archive.txt "URL". yt-dlp writes one line per finished download to that file and skips anything already listed on the next run, even if you moved or renamed the files.

What is in the yt-dlp archive file?

One line per video: the extractor name and the video's ID, separated by a space, such as "soundcloud 290" or "youtube dQw4w9WgXcQ". It's plain text, so you can edit it, merge two of them or delete a line to download that video again.

Why does yt-dlp stop straight away with --break-on-existing?

--break-on-existing stops at the first video that's already in the archive. That's meant for channels and feeds listed newest first. On a playlist listed oldest first, the first entry is usually one you already have, so it stops immediately. Leave the option off for those.

How do I add videos I already have to the archive without downloading them again?

Run the same URL with --skip-download --force-write-archive --download-archive archive.txt. yt-dlp resolves every video and writes its line to the archive without downloading anything.

Does the archive file stop yt-dlp from fetching the playlist?

No. yt-dlp still reads the playlist or channel listing on every run; the archive only skips the download of entries it knows. On big channels, --break-on-existing (newest-first sources) is what saves the time.

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.