ytdl-sub

Self-hosted media archiving, honestly reviewed. No marketing fluff, just what you get when you stop relying on streaming.

TL;DR

• What it is: GPL-3.0 command-line tool that wraps yt-dlp to download YouTube channels, playlists, SoundCloud, and Bandcamp content — and formats everything so Plex, Jellyfin, Emby, and Kodi treat it like native TV shows or music libraries [2].
• Who it’s for: Self-hosters who already run Jellyfin or Plex and want YouTube channels to appear as proper TV show seasons, not a chaotic folder of files. Also serious music archivists pulling SoundCloud and Bandcamp discographies with correct tags [1][2].
• Cost: $0. GPL-3.0, no SaaS tier, no limits. Your only cost is the VPS or NAS running it and storage [README].
• Key strength: The prebuilt preset system is genuinely good. A 10-line YAML file can download two months of Linus Tech Tips as a properly structured Plex TV show. No plugins, no scrapers, no separate metadata agents [2].
• Key weakness: It is a command-line tool that speaks YAML. If you need a browser-based library manager with search, watch history, and a Netflix-style UI, look at Tube Archivist instead — ytdl-sub has no persistent web interface by design [1][4].

---

What is ytdl-sub

ytdl-sub is a thin automation layer on top of yt-dlp, the de facto standard for downloading video from YouTube and hundreds of other sites. What yt-dlp does is download media; what ytdl-sub adds is the metadata scaffolding — NFO files, thumbnail placement, season/episode numbering, music tags — that turns a pile of MP4 files into something a media server can actually index correctly.

The GitHub description puts it plainly: “Lightweight tool to automate downloading and metadata generation with yt-dlp” [README]. That’s accurate. It is not a media server, not a library browser, not a GUI downloader. It is a scheduler and formatter for yt-dlp that speaks the file conventions of Kodi, Jellyfin, Plex, and Emby natively.

The core model is YAML subscription files. You define what you want to download and which preset to apply, and ytdl-sub handles the rest — including tracking what it has already downloaded so successive runs only pull new content [2]. The developer posted to r/selfhosted describing the three main use cases: YouTube channels or playlists formatted as TV shows, music content from YouTube, SoundCloud, or Bandcamp with proper tags, and music videos [2]. That’s still the accurate scope — it hasn’t tried to become a general-purpose media manager.

The project sits at 2,757 GitHub stars. It’s an active one-maintainer project with community contributions. The Discord has several hundred active members. It is not a dead project, but it is also not a large engineering team [README].

---

Why people choose it

The primary driver for switching to ytdl-sub, based on the first-hand accounts, is frustration with Tube Archivist. The noted.lol reviewer [1] describes switching after persistent Tube Archivist crashes during updates and random failures to embed thumbnails. They had already tried multiple GUI-based solutions and found them unreliable. ytdl-sub’s appeal was exactly what you’d expect: fewer moving parts, nothing crashes during a web UI update because there is no web UI, and the YAML files are portable and version-controllable.

The second driver is media server integration. If you’re already running Jellyfin or Plex, you’ve probably already fought with getting YouTube downloads to appear correctly. Random files don’t get metadata, channels become unnavigable, thumbnails don’t show. ytdl-sub solves this by generating the exact NFO files and thumbnail placements those servers expect — no plugins required [1][2]. The screenshots in the README show YouTube channels appearing as proper TV show series with episode thumbnails and season groupings in Plex and Jellyfin. That’s the actual value proposition.

The third driver is breadth. Most YouTube archivers handle YouTube. ytdl-sub also handles SoundCloud discographies with proper beets-based music tagging, Bandcamp releases, and music videos as a distinct content type [README][2]. For someone building a comprehensive self-hosted music library alongside a video library, that matters.

Versus Tube Archivist. This is the sharpest comparison. Tube Archivist has a proper web UI, search, watch tracking, and feels more like a media application. ytdl-sub has none of that — it runs, formats files, and exits. The tradeoff is reliability and simplicity: fewer failure modes, no database to corrupt, no web server to misconfigure [1][4]. One reviewer explicitly switched in this direction after Tube Archivist instability [1].

Versus raw yt-dlp. Technically you can script yt-dlp directly and handle your own metadata. ytdl-sub saves you from writing and maintaining that scripting layer. The presets handle the edge cases: what happens when a channel has 800 videos and you only want the last 60 days, how to number episodes by upload date, how to format music tags for Navidrome compatibility [2][README].

Versus Pinchflat and Tubesync. Pinchflat is newer, simpler, has a basic web UI, and focuses only on YouTube. Tubesync is described as “Sonarr but for YouTube” with a web interface. Both are easier to get started with. ytdl-sub wins on flexibility and breadth (music sources, scripting, custom presets) and loses on onboarding experience [4].

---

Features

Subscription and preset system:

• YAML subscription files define what to download and how to format it [README]
• Prebuilt presets for all major media players: Plex TV Show by Date, Jellyfin TV Show, Kodi, Emby [README][2]
• Global overrides via a __preset__ block — set your directory once and it applies everywhere [README]
• Date range filtering: only_recent_date_range: "2months" keeps rolling windows instead of accumulating forever [2]
• Multi-URL subscriptions: one TV show can pull from multiple channels [README]
• Season tagging: define named seasons with separate URLs [README]
• Inline genre, content rating, and other tag overrides using terse syntax like = Kids | = TV-Y [2]

Media type support:

• YouTube channels, playlists, individual videos [README]
• SoundCloud discographies with beets-based music tagging for Navidrome/Gonic [README]
• Bandcamp releases and discographies [README]
• Music videos as a distinct type with appropriate metadata [README][2]

Scripting:

• Template variables in any string field using {variable_name} syntax [7]
• Entry variables from yt-dlp’s info.json (title, upload date, channel, etc.) [7]
• Custom override variables for reusable expressions [7]
• Built-in sanitization via _sanitized suffix on any variable [7]
• Scripting functions like %replace() for transformations [7]

Installation options:

• Docker and Docker Compose (most common) [README]
• Linux binary (curl download, chmod, done) [1]
• ARM and Windows portable binaries [2]
• pip install [2]
• Browser-based VS Code GUI via the ytdl-sub-gui Docker image — runs VS Code in browser with ytdl-sub preinstalled [2]

Automation:

• Idempotent downloads — successive runs pick up where they left off [2]
• Cron integration for automated recurring downloads [1]
• Cookie file support for authenticated downloads [README]
• Pass-through to yt-dlp Python API for any option ytdl-sub doesn’t expose directly [README]

---

Pricing: SaaS vs self-hosted math

ytdl-sub has no paid tier. GPL-3.0, free forever, no telemetry, no license server. The relevant cost comparisons are what you’d pay for the content access itself.

YouTube Premium: $13.99/month in the US for ad-free viewing and offline downloads. ytdl-sub replaces the offline download function entirely and eliminates ads by downloading directly. Annual savings: ~$168/year, assuming you were paying for Premium primarily for downloads and offline access.

Infrastructure cost for ytdl-sub:

• The tool itself: $0
• A VPS to run it on: $5–10/month on Hetzner or Contabo (though if you’re already running Jellyfin or Plex, you likely already have the server and ytdl-sub adds near-zero overhead)
• Storage: the real ongoing cost — a channel archive grows. Plan for this.

Tube Archivist for comparison: Also free and open-source, but requires more RAM (the Elasticsearch dependency is heavy) and more storage for its database layer. ytdl-sub’s footprint is lower because it doesn’t maintain a persistent database — everything is in files and YAML.

The cost math is simple: if you’re paying for YouTube Premium primarily for downloads or offline access, ytdl-sub is the obvious replacement cost-wise. If you’re not paying for anything currently, ytdl-sub is still free, but you should factor your storage costs and the time investment.

---

Deployment reality check

The noted.lol reviewer describes the Linux install as manageable if you’re comfortable with a terminal: download the binary with curl, chmod it, create two YAML files, run it [1]. That’s accurate for the minimal case. Docker is the more common path in the selfhosted community and probably the better default.

What you actually need:

• A Linux system with Docker (or Docker Compose) — this is the recommended path [README]
• Alternatively: a Linux system with FFmpeg installed for the native binary [1]
• Storage — plan generously; video archives grow fast
• Cron or a similar scheduler if you want automated recurring downloads [1]
• A cookie file from your browser if you’re downloading age-restricted or members-only content [README]

What can go sideways:

The setup pain is real for first-timers. One Reddit user [5] reported issues getting it working with Docker and ended up running it on Windows locally. The YAML configuration is not difficult if you’ve read YAML before, but the preset system has a learning curve — understanding which preset does what, and how to override specific fields without breaking the preset’s assumptions, takes some documentation reading [1][2].

Single video downloads (versus whole channels) are not the primary design intent. A Reddit user asked about this directly [5] and found the answer was not obvious. ytdl-sub is designed around subscriptions — recurring downloads from a source. If you want to download one specific video and slot it into your library, yt-dlp directly is probably the right tool.

The noted.lol reviewer specifically notes that they had better success running ytdl-sub natively on Linux with cron than via Docker for their use case [1]. This is a minority opinion — Docker is the more common recommendation — but it’s worth knowing that the native binary path is viable and sometimes preferable for cron control.

Time estimates:

• Technical user who has deployed Docker before: 20–40 minutes to a working download
• Technical user reading the docs carefully and customizing presets: 1–3 hours
• Non-technical user: this is not a non-technical user tool. The command line is not optional. Budget a full day or find someone to configure it.

---

Pros and Cons

Pros

• Free and GPL-3.0 licensed. No tiers, no limits, no license server. [README]
• Prebuilt presets that actually work. The Plex, Jellyfin, Emby, and Kodi presets generate correct metadata without extra plugins. A channel appears as a TV show with proper seasons, thumbnails, and episode metadata out of the box [1][2].
• Idempotent operation. Run it again tomorrow and it downloads only what’s new. No duplicate files, no re-downloading a 500-video archive [2].
• Multi-source music support. SoundCloud and Bandcamp with beets-based tagging puts it in a different category from YouTube-only archivers [README][2].
• Low resource overhead. No database, no persistent server, no Elasticsearch. Runs, downloads, exits [1].
• Portable installation options. Binary, Docker, pip, or native — and an in-browser VS Code GUI for users who don’t want to SSH [2].
• Scripting flexibility. If the presets don’t do exactly what you want, the variable and scripting system covers most edge cases without writing Python [7].
• Cron-native design. It was built to be run on a schedule. No awkward workarounds for automation [1][2].

Cons

• No web UI for library browsing. ytdl-sub downloads and formats files. What you do with those files — browsing, searching, watch tracking — is someone else’s job (Jellyfin, Plex, etc.) [1][4].
• CLI-first with a real learning curve. The reviewer at noted.lol specifically calls it “Advanced YouTube Downloading that’s Worth the Effort” — the effort part is real [1]. First-time setup requires reading documentation.
• YAML config complexity at scale. A simple subscription file is simple. A complex one with multiple presets, custom overrides, scripting functions, and multi-URL channels is not trivial to debug.
• Single video downloads are awkward. The tool is built around subscriptions to sources, not one-off downloads. Grabbing a specific video into your library structure takes workarounds [5].
• No watch history or search. If you need to know which videos you’ve watched or search your archive by keyword, ytdl-sub doesn’t provide that. Your media server does, or you don’t have it.
• One primary maintainer. 2,757 stars is healthy but it’s not a large project. Long-term maintenance risk is real if the maintainer moves on [README].
• Docker issues reported. At least one user [5] abandoned Docker in favor of running natively on Windows due to setup problems. The Docker path isn’t always smooth.

---

Who should use this / who shouldn’t

Use ytdl-sub if:

• You already run Jellyfin, Plex, Emby, or Kodi and want YouTube channels to appear as proper TV shows without installing extra plugins or scrapers.
• You’re an archiver — you want a complete, growing library of specific channels or playlists stored locally, not just a download queue.
• You want SoundCloud or Bandcamp music downloaded with proper music tags for Navidrome or a similar music server.
• You’re comfortable with YAML files and the command line, or willing to spend an afternoon learning.
• You want automation — scheduled, idempotent downloads that just run and require no intervention.

Skip it — use Tube Archivist instead — if:

• You need a web UI to browse your YouTube library, track what you’ve watched, and search by keyword.
• You’re archiving YouTube specifically and don’t need multi-source music support.
• You want something that feels like an application rather than a configured tool.

Skip it — use Pinchflat instead — if:

• You want simpler setup with a basic web UI and you only care about YouTube content.
• The YAML configuration system feels like too much overhead for your use case.

Skip it — use raw yt-dlp instead — if:

• You’re downloading one-off videos, not building an organized library.
• You don’t need media server metadata integration.

Skip it entirely if:

• You’re not comfortable with a terminal. There’s no version of this tool that works around that requirement.
• You want to browse and discover content, not just archive it. Self-hosted media servers don’t replace YouTube’s recommendation algorithm.

---

Alternatives worth considering

From the AlternativeTo listing and community discussions:

• Tube Archivist — Full web UI, search, watch tracking, built-in player. More RAM-hungry (Elasticsearch required). GPL-3.0. The noted.lol reviewer switched away from it due to instability, but for many users it’s the better fit if you want a proper application [1][4].
• Pinchflat — Lighter, simpler, AGPL-3.0, YouTube-only. Web UI for managing subscriptions. If ytdl-sub’s YAML approach feels like overkill, Pinchflat is the easier onramp [4].
• Tubesync — Described as “Sonarr but for YouTube.” Web UI, PVR-style management, AGPL-3.0. More opinionated than ytdl-sub, less flexible [4].
• yt-dlp directly — The underlying tool. No metadata formatting, no subscription tracking, but maximum control and zero configuration overhead. Right for one-off downloads; wrong for building an organized library.
• Jellyfin’s built-in YouTube plugin — Exists but historically unreliable and limited. Not a serious alternative for archiving.

For most Jellyfin/Plex users the realistic shortlist is ytdl-sub vs Tube Archivist. Pick ytdl-sub if you want file-based simplicity and multi-source support. Pick Tube Archivist if you want a persistent web UI and search.

---

Bottom line

ytdl-sub does one thing: it takes yt-dlp downloads and formats them correctly for your media server. It does that thing well, reliably, and without charging you for it. The prebuilt presets for Plex and Jellyfin are genuinely good — a real YAML file that downloads two YouTube channels as properly structured TV shows is ten lines [2]. The music support across YouTube, SoundCloud, and Bandcamp is a meaningful differentiator from YouTube-only archivers. The command-line, YAML-first design is both the tool’s strength (reliability, composability, low overhead) and its hard constraint — if you need a GUI, this isn’t it.

The honest target user is someone who is already comfortable in a terminal, already running a self-hosted media server, and wants their YouTube subscriptions to show up in Jellyfin looking like television instead of a file dump. For that person, ytdl-sub is the right answer. Everyone else should look at Tube Archivist or Pinchflat first and come back to ytdl-sub when they’ve outgrown the simpler options.

---

Sources

1. Jeremy, noted.lol — “ytdl-sub: Advanced YouTube Downloading that’s Worth the Effort” (Sep 4, 2025). https://noted.lol/ytdl-sub/
2. FrankMagecaster (project developer), r/selfhosted — “ytdl-sub: Automate YouTube downloads and metadata generation for usage in Kodi/Jellyfin/Plex/etc + more” (2023). https://www.reddit.com/r/selfhosted/comments/17nc73a/ytdlsub_automate_youtube_downloads_and_metadata/
3. noted.lol — Self-Hosting tag page (context). https://noted.lol/tag/self-hosting/
4. AlternativeTo — “ytdl-sub Alternatives: Top 3 YouTube Downloaders & Similar Apps” (updated Mar 28, 2024). https://alternativeto.net/software/ytdl-sub/
5. geoffrey801, r/selfhosted — “Downloading single videos instead of whole channel YTDL-sub”. https://www.reddit.com/r/selfhosted/comments/1hwys9x/downloading_single_videos_instead_of_whole/
6. medevel.com — “15 Free YouTube-Download GUIs and Apps for The Famous Yt-dl App”. https://medevel.com/15-free-youtube-download-guis-and-apps-for-the-famous-yt-dl-app-for-windows-linux-and-macos/
7. ytdl-sub documentation — “Scripting”. https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/index.html

Primary sources:

• GitHub repository and README: https://github.com/jmbannon/ytdl-sub (2,757 stars, GPL-3.0)
• Official documentation: https://ytdl-sub.readthedocs.io/en/latest/