YTPTube: a self-hosted queue and automation layer around yt-dlp

The gap between a yt-dlp command and a download library

yt-dlp is a command line program. It downloads one invocation at a time and forgets everything afterwards. If you want to check a channel every night, keep a consistent output template, and produce sidecar metadata that Jellyfin or Kodi will read, you end up writing shell scripts and a cron table. YTPTube exists to replace that glue. The README describes it as a self-hosted download manager, automation interface, and media library preparation layer for yt-dlp, and the three pieces map onto three named concepts: Tasks, Presets and Conditions. Tasks check channels, playlists, feeds and supported custom sources on a schedule. Presets store reusable yt-dlp options, output templates, paths, cookies and post-processing settings. Conditions inspect metadata returned by yt-dlp and apply matching options. The target user is someone with a machine that stays on, a media server, and enough patience to configure options once rather than per download. It is not aimed at someone who wants a hosted service, and it is not aimed at a team that needs shared governance of the codebase.

Tasks, Presets and Conditions as three separable mechanisms

The design choice worth noting is that the three automation tools can be used separately or together, according to the README. That means you can run YTPTube purely as a manual download queue with a file browser and never touch scheduling. The data flow is roughly this: a URL or a Task supplies input, yt-dlp extracts metadata, Conditions optionally read that metadata and decide which additional options apply, a Preset supplies the base option set and output paths, and the file lands in the download directory with optional post-processing. Concurrency is handled at two levels, global and per-extractor limits, which matters because hammering a single site with parallel requests is the fastest way to get rate limited. The queue also has archive controls, live logs and diagnostics. Notifications go out through Apprise or direct HTTP webhooks for selected events. On the media side, the NFO Maker integration converts yt-dlp metadata into Kodi-style TV or movie .nfo sidecars, cleans descriptions, creates stable IDs and keeps each NFO beside its media file. Scheduled Tasks can separately produce collection metadata such as tvshow.nfo, .info.json and artwork. A separate info-reader Preset writes channel and season layouts for Jellyfin, Emby, Plex and WatchState workflows. The README points to a features document for the three workflows and their limits, which is a hint that the limits are real and worth reading before you rely on any of them.

Getting it running with compose.yaml

The repository ships a compose.yaml that the README says runs YTPTube with the bundled POT provider, Chromium browser extraction and FlareSolverr support, plus commented host-specific examples for hardware acceleration and NFS or SMB storage. The documented quick start is two commands. First create the directories: mkdir -p ./{config,downloads/{files,tmp}}. Then start the container: docker compose up -d. The interface listens on http://localhost:8081 and the first thing you do is create a local account. The bare docker run form is also documented, and it sets two environment variables explicitly: YTP_TEMP_PATH=/downloads/tmp and YTP_DOWNLOAD_PATH=/downloads/files, with ./config mounted at /config and ./downloads at /downloads. The container runs as your user and group IDs, which the README explains keeps downloaded files accessible to the host account. Podman users are told they can replace the user line with userns_mode: keep-id and run podman-compose up -d. There are also Unraid and native build paths: a Community Applications template, and Windows, macOS and Linux archives on the releases page. The README references an environment variable reference in the FAQ for additional application settings, so the two variables above are the minimum rather than the full surface.

Authentication is a boundary, not a feature

The security section is blunt in a way that most project READMEs are not. It states that authenticated users are instance administrators and can pass yt-dlp options, including options that execute commands. That is not a permissions model with roles; it is a single trust tier. The README instructs you not to expose YTPTube to an untrusted network without authentication, and says authentication should only be disabled when a trusted reverse proxy controls access or the instance is restricted to a private network. Read that as an architectural constraint. If you want a household where one person can queue downloads and another can edit Presets, the documentation does not describe a way to separate those. The practical consequence is that YTPTube belongs behind a VPN or an authenticating proxy rather than on a public hostname. The same section points to security recommendations in the FAQ and to GitHub security advisories for reporting vulnerabilities.

A personal-first project with a closed contribution door

The project policy is explicit and unusual. YTPTube is described as a personal-first project. Contributions are welcome only after approval from the maintainer following prior discussion, and unsolicited pull requests will be declined. The README also states that AI-assisted tools have been used and will continue to be used where the maintainer finds them useful, and that the project is built for the maintainer's own needs and use cases. This is not a flaw in the software, but it is a material fact about adopting it. You are consuming a tool whose roadmap follows one person's priorities. If your requirement diverges from those priorities, the documented path is a prior conversation, not a patch. For a self-hosted utility that sits on top of another tool, that may be acceptable. For anything you intend to depend on organisationally, it is a risk you should price in. The README ends mid-sentence in the supplied text, so the full closing statement of that policy is not available here.

Where YTPTube is the wrong tool

The most obvious limitation is inherited rather than invented. YTPTube is a layer over yt-dlp, so anything yt-dlp cannot extract, YTPTube cannot download. When a site changes its player, the fix has to land upstream first. The README lists mitigations for this class of problem: curl-cffi impersonation, a bundled PO-token provider, optional browser extraction over an existing Chrome instance, and optional integration with FlareSolverr or Trawl to bypass some WAF protection. Those are workarounds for specific defences, not a general guarantee. The second limitation is the trust model described above. The third is scope: the README mentions an optional terminal interface for direct yt-dlp control, which is a useful escape hatch, but it also implies that the web layer does not cover every yt-dlp option in a first-class way. If your workflow is a single URL once a month, the compose file, the account, the reverse proxy and the storage layout are more work than the problem deserves. A shell alias would do.

Compared with running yt-dlp from cron

The honest alternative is not another download manager. It is yt-dlp itself plus cron, or a small systemd timer, and a naming convention. That approach has real advantages. There is no web server to secure, no account to manage, no container to update, and no second project between you and the extractor. It also has a real cost: you write and maintain the scheduling, the archive file handling, the output templates, and any metadata sidecars yourself. YTPTube's difference in approach is that it moves those concerns into configuration inside an application, with a queue, live logs and diagnostics attached. The trade is that you now have a service to keep patched. The README's own framing supports this reading, since it presents Tasks, Presets and Conditions as things you would otherwise script. If your cron line is five flags long, keep the cron line. If it has grown branches for different channels, different output templates and different post-processing, the application layer starts to earn its place.

Licence, upgrades and what to check before you commit

YTPTube is MIT licensed, which is permissive and places few obligations on you beyond retaining the licence notice. This is not legal advice; read the licence text and your own organisation's policy. The repository's default branch is dev, and the release cadence visible in the supplied material is fast, with v2.7.0, v2.7.1 and v2.7.2 landing within roughly three weeks in August 2026. The README documents Docker, Podman, Unraid and native archives, so you can pin a tag rather than track latest, and the compose file is in the repository for you to diff on upgrade. Because the app writes NFO sidecars, .info.json files and artwork into your download tree, an upgrade that changes naming behaviour has a blast radius beyond the container. Before adopting, verify three things: that your reverse proxy blocks unauthenticated access, that your downloads and config directories are on storage you can back up, and that the three media library workflows described in the features document match the layout your media server actually scans. If the info-reader Preset does not produce the channel and season structure your server expects, you will be renaming directories by hand.

Editorial conclusion

Adopt YTPTube if you already run yt-dlp on a home server and want scheduled channel checks, reusable option sets and Kodi-style NFO sidecars behind one web interface. Do not adopt it if you need an open contribution process, a multi-tenant deployment, or a tool that will keep working when an extractor breaks. Before committing, verify that your reverse proxy enforces authentication, since the README states that authenticated users are instance administrators and can pass yt-dlp options that execute commands.

Official sources

1. arabcoders/ytptube on GitHub
2. Issues
3. License: MIT
4. README
5. Releases