Ytdl-sub

ytdl-sub is a headless command-line tool that automates downloading and metadata generation for self-hosted media libraries.

  • Downloaders
  • Media Applications
  • Tools & Utilities
ytdl-sub is a headless command-line tool that automates downloading and metadata generation for self-hosted media libraries. It fetches video and audio through yt-dlp and organises the output with ready-to-use file names and metadata for players such as Jellyfin, Plex, Emby, and Kodi. It suits homelab users who want fully automated, server-side downloads without a web interface. No extra plugins or external scrapers are required, which keeps setup simpler than managing downloads by hand.

Platform availability

Available on 2 of 10 platforms

  • Unraid
  • TrueNAS (not listed)
  • Umbrel (not listed)
  • ZimaOS (not listed)
  • Proxmox (not listed)
  • Helm (not listed)
  • Mac (not listed)
  • Windows (not listed)
  • Linux (not listed)
  • Any server

Health score?A 0-100 score computed nightly from four factors: maintained (40%: recent commits and steady activity), popular (25%: GitHub stars, log scale), easy to install (20%: platforms, install notes, setup guides, Docker image) and light to run (15%: minimum RAM, ARM support). When the source code has been checked, a fifth factor, security check (20%: automated scan for committed secrets, unsafe desktop-app settings, known-vulnerable dependencies and project hygiene; any serious finding caps it at 20), is added. Factors without data are left out and the rest are rescaled.

79/100 Good

Maintained
93last commit 5 days ago
Popular
703,041 GitHub stars
Easy to install
452 install platforms, install notes, Docker image
Light to run
No data
Security check
95no serious findings, CI, tests

Based on 4 of 5 factors.

Availability: platform listings confirmed today, links checked 16 days ago

GitHub stars
3,041
Open issues
123
Last commit
2026-11-16
Latest release
2026.11.16.post1
License
GPL-3.0
Activity
rising

Checked 5 days ago - source: GitHub (jmbannon/ytdl-sub)

Resources & Compatibility

Requirements not published yet.

Checked 54 days ago - source: Docker Hub image tags and published docs

First-install notes

  • Make the downloaded ytdl-sub runnable Download the latest ytdl-sub binary, then run chmod +x ytdl-sub so Linux allows it to run. If you skip this, the command may fail with a permission error or not work as expected. source
  • Create a subscriptions.yaml before starting Create a subscriptions.yaml file that lists the channels, playlists, or albums you want and sets the folders where TV shows, music, and music videos should be saved. Without it, ytdl-sub does not know what to download or where to put the files. source
  • Set working and log folders in config In configuration.yaml, set working_directory and lock_directory to writable folders you will not delete, and set ffmpeg_path or ffprobe_path if your system does not find those video tools automatically. These settings keep ytdl-sub from writing temporary files to the wrong place and help prevent failed or overlapping runs. source

Fetched 53 days ago - each note links to its source

Alternatives (1)

  • tube archivist - Subscribe, download, and organize YouTube videos in a searchable library with playback, viewing history tracking, batch downloads, and chan…

Checked 40 days ago - source: AlternativeTo

Common questions

Do I need to build every download rule from scratch?

No. Subscriptions are YAML files that import presets, and ytdl-sub includes many prebuilt presets that handle config-building for media handling and output.

What should I set in configuration.yaml to reduce failed or overlapping runs?

Set working_directory and lock_directory to writable folders you will not delete. If the system does not find ffmpeg or ffprobe, set ffmpeg_path or ffprobe_path to their locations.

Why might the downloaded ytdl-sub Linux binary fail to run?

It may need to be marked executable with chmod +x ytdl-sub. Skipping this can cause a permission error.

What command can I use to test a subscription?

Navigate to the directory containing your subscriptions.yaml file, then run ytdl-sub --dry-run sub.

How can I replace a file that ytdl-sub has already archived?

Force ytdl-sub to re-download the file to replace an archived file that is lower resolution, missing subtitles, or corrupt.

Answers sourced from github.com, github.com, github.com, www.reddit.com, ytdl-sub.readthedocs.io

Community

Collected 49 days ago - public community threads