Ytdl-sub
ytdl-sub is a headless command-line tool that automates downloading and metadata generation for self-hosted media libraries.
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
Variants
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
- ytdl-sub 0.3.0 release - Automate YouTube downloads and ... - Reddit (reddit)
- r/selfhosted on Reddit: ytdl-sub: Automate YouTube downloads and ... (reddit)
- Help running ytdl-sub : r/selfhosted - Reddit (reddit)
Collected 49 days ago - public community threads