TubeSync

Last reviewed Sep 13, 2026 · 916 words

TubeSync works beautifully right up until the day YouTube changes something, at which point every download fails until you pull a new image. That is not a criticism of TubeSync (AGPL-3.0, Python, 2,791 stars) so much as the physics of the category: it is a Django wrapper around yt-dlp, and yt-dlp is in a permanent arms race with the platform. Accept that you will update the container roughly monthly and it becomes the least-effort way I know to keep a set of channels on your own disk, playable in Jellyfin or Plex like any other show.

What it actually does that a cron job doesn't

You add a source (a channel, a channel's playlists, or a single playlist), set an index frequency and a quality profile, and TubeSync keeps checking for new videos in the background and downloads whatever matches. The part that saves real effort is the output: videos land in a channel/title.mkv structure with a thumbnail, an NFO file carrying the description and upload date, and optional subtitles and metadata JSON. Point a Jellyfin library of type "Shows" at the folder and each channel appears as a series with proper artwork. Two filters do most of the pruning work: a minimum and maximum video duration per source, and a "download cap" that only fetches videos published after a date, so subscribing to a channel with 3,000 uploads does not fetch 3,000 uploads.

The 5-minute deployment

It is Docker-only, and the compose file is short:

services:
  tubesync:
    image: ghcr.io/meeb/tubesync:latest
    ports:
      - "4848:4848"
    volumes:
      - ./config:/config
      - /mnt/media/youtube:/downloads
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Europe/London
    restart: unless-stopped

The UI is on port 4848 with no authentication by default, so keep it on the LAN or add auth at the reverse proxy; there are HTTP_USER and HTTP_PASS environment variables if you want the container to demand basic auth itself. SQLite is the default database and is fine for a few dozen sources. If you plan on hundreds of channels, the project supports PostgreSQL through a DATABASE_CONNECTION variable, and you will want it, because the indexing writes get slow on SQLite once the media table hits tens of thousands of rows.

The 512 MB RAM floor in our catalogue is honest for the app; what it does not cover is ffmpeg remuxing, which spikes briefly per download. On a Raspberry Pi 4 it runs, but transcoding-free formats (choose profiles that match audio and video without re-encoding) keep the CPU out of trouble.

Storage is the real cost, not RAM

A 1080p video from a typical channel runs 100 to 300 MB for 10 to 20 minutes. Twenty active channels posting weekly will add somewhere around 10 to 20 GB a month, and 4K sources multiply that by 4 or 5. Three habits keep this bounded: use the "delete media older than N days" option per source for news-style channels, set the quality cap to 1080p unless you truly watch on a 4K panel, and use the "skip videos longer than" filter to avoid 8-hour livestream VODs. TubeSync also honours a per-source "download only from this date" setting, which is the difference between an archive and a subscription.

The upgrade discipline nobody warns you about

When downloads start failing with extractor errors, the fix is nearly always docker compose pull && docker compose up -d, because the maintainer bumps yt-dlp inside the image regularly. Pin nothing. Check the Tasks page in the UI, which shows the queue and error messages per video, before assuming the whole thing broke; a single geo-blocked or members-only video errors on its own without affecting the rest. If you use Watchtower, TubeSync is a container where automatic updates are a net win rather than a risk.

Two limits to know. TubeSync does not log in, so age-restricted or members-only content is out unless you supply cookies, which the project supports but which is fragile. And it is YouTube-first; other sites that yt-dlp handles may work but are not the design target.

Pinchflat, ytdl-sub, or TubeSync

Pinchflat is the newer, faster-moving competitor with a very similar goal and a slicker UI; if you are starting today and want the same Jellyfin-friendly output, try it first. ytdl-sub is the power-user pick, config-file driven, for people who want exact control over naming and metadata. TubeSync's advantages are maturity, a straightforward web UI a non-technical household member can use, and a large installed base that surfaces breakage quickly on GitHub. The wider media server category covers the players these all feed. Anyone weighing this against paying the platform can read our YouTube Premium alternatives rundown for the honest trade-offs.

What I'd do

Run TubeSync on the same box as Jellyfin with /downloads on the media pool, 1080p cap, a 30-day retention on news channels and unlimited on the 5 or 6 creators I actually rewatch. Put it behind the reverse proxy with auth, let Watchtower update it nightly, and glance at the Tasks page once a week. If I were building fresh in 2026 I would trial Pinchflat alongside for a month and keep whichever one broke less, but TubeSync has never left me without a working library for more than a day.