Youtarr

Youtarr is a self-hosted YouTube downloader that automatically downloads videos from your favorite channels and playlists. It provides metadata for multiple media servers, mirrors your subscribed YouTube playlists into Plex, Jellyfin, and Emby as native playlists, pulls watch status back from those servers so you can filter your library by what's been watched, and offers optional Plex integration for automatic library refreshes. Learn more at youtarr.com.

Don't want to self-host? You can also run Youtarr on ElfHosted with a managed deployment – see their Youtarr docs.

Like Youtarr? Consider supporting the project on Patreon to help keep it free and actively developed!

https://github.com/user-attachments/assets/a80548fc-bcf9-4ad0-889c-dbd5aac250ee

Why Youtarr?

• No Ads or Tracking: Watch YouTube content without interruptions
• Offline Viewing: Access your videos anytime, even without internet
• Archive Content: Preserve videos before they're deleted or made private
• Works Standalone: Full functionality without requiring any media server
• Family-Friendly: Create curated, safe YouTube experiences with multi-library support
• Media Server Ready: Downloads videos with proper organization and metadata for Plex, Kodi, Jellyfin, and Emby.

Key Features

• Smart Downloads: Pre-validate manually pasted URLs with metadata preview before downloading
• Channel Subscriptions: Subscribe to channels and auto-download new videos, shorts, and streams with per-tab controls
• Playlist Subscriptions: Subscribe to YouTube playlists and auto-download their videos into the right channel folders; Youtarr mirrors each playlist into Plex, Jellyfin, and Emby as a native playlist and writes a universal .m3u file for any other player
• Browse Channels: View and search all videos from subscribed channels with advanced filtering, tabbed views for Videos/Shorts/Streams, and contextual publish date accuracy tips
• Find on YouTube: Search YouTube from inside Youtarr, see which results are already downloaded or missing, and click any result to queue a download
• In-App Playback: Click any thumbnail to open a detail modal with extended metadata and in-browser streaming of downloaded videos; no media server required
• Channel Grouping & Multi-Library Support: Organize channels into custom subfolders (e.g., __kids, __music, __news) to create separate media server libraries
• Smart Organization: Videos organized by channel with metadata and thumbnails
• SponsorBlock Integration: Remove sponsored segments automatically
• Quality Control: Global and per-channel resolution settings (360p to 4K)
• Download History: Track what you've downloaded with smart duplicate prevention
• Watch Status Sync: Pull per-video watched state from Plex, Jellyfin, and Emby (every user on the server, not just yours), show a Watched chip on listing pages, and filter your library by watched or unwatched. One-way sync; Youtarr never writes back to your servers
• Metadata Generation: NFO files, poster images and embedded MP4 metadata for all media servers
• Scheduled Downloads: Configure automatic downloads on your schedule (cron-based)
• Auto-Cleanup: Age and space-based removal of videos with dry-run previews
• Filesystem Rescan: Move, rename, or convert downloaded files outside Youtarr (e.g., .mp4 to .mkv) and trigger a rescan from Settings -> Maintenance to reconcile the database; daily and startup scans pick up changes automatically
• Discord Notifications: Optional webhook alerts for new downloads
• Web Interface: Manage everything through a responsive (PC or mobile) web UI
• Secure Access: Built-in authentication with admin controls
• REST API: Full API with interactive Swagger/OpenAPI documentation for automation and integrations
• Platform Flexible: Configurable storage paths and guides for deployment to multiple platforms and architectures
• Unraid Ready: Community Applications template (via DialmasterOrg repo) with headless-friendly credential presets
• Powered by yt-dlp: Uses yt-dlp under the hood for YouTube integration and downloads
• Content Ratings: Add per-video and per-channel content ratings (normalized to common media-server values like G, PG, PG-13, R, NC-17, TV-*). Ratings can be set per-download, via channel defaults, or derived from yt-dlp metadata; they show up as badges and can be used for automated policies.

How Youtarr compares

Youtarr predates Pinchflat (first commits May 2023 vs. January 2024); the two arrived at similar solutions independently and have evolved in parallel since. For a side-by-side of where Youtarr, Pinchflat, and Tube Archivist differ on Plex integration, in-app playback, watch-status tracking, content ratings, REST API, filename templating, and transcript search, see the comparison doc.

Quick Start

You'll need Docker, Docker Compose, Git, and a Bash shell (Git Bash on Windows). See the Installation Guide for prerequisites, install methods, initial setup, and updating.

Heads up: Youtarr runs exclusively via Docker; direct npm start/Node deployments are unsupported.

Want to try unreleased features? See Using Development Builds for the bleeding-edge dev-latest image.

Database note for Docker Desktop/ARM/NAS users: Fresh installs started with ./start.sh use Docker named-volume storage for MariaDB. Existing bind-mounted installs and plain docker compose up -d installs may use ./database; on virtualized filesystems this can be risky for MariaDB schema migrations. If you see Table ... doesn't exist in engine or Incorrect information in file errors, or if you want to proactively migrate, see Database Management.

Documentation

Setup & Configuration

• Installation Guide - Install methods, initial setup, and updating
• Usage Guide - Step-by-step tutorials for common tasks
• Configuration Reference - All configuration options
• Environment Variables - Docker environment settings
• Authentication Setup - Security and access control

Media Server Setup

• Media Servers Overview - Comparison and quick start
• Plex Integration - Full Plex setup guide
• Kodi Setup - Kodi configuration
• Jellyfin Setup - Jellyfin integration
• Emby Setup - Emby configuration
• Media Server Playlists - Sync subscribed playlists to Plex, Jellyfin, and Emby

Platform Guides

• Synology NAS - DSM 7+ optimized setup
• Unraid - Community Applications template
• External Database - Using existing MariaDB/MySQL

Advanced Topics

• Backup & Restore - Backup your configuration and database, restore to new systems
• Database Management - Database configuration and maintenance
• Docker Configuration - Advanced Docker settings
• Development Guide - Contributing, development setup, and using bleeding-edge dev builds
• API Documentation - Interactive Swagger/OpenAPI documentation (requires running instance)

Help & Support

• Troubleshooting Guide - Common issues and solutions
• GitHub Issues - Report bugs or request features
• Discord Server - Join the community for help and discussion

Contributing

Interested in contributing to Youtarr? We welcome contributions of all kinds!

• Contributing Guide - How to contribute, coding standards, and development workflow
• Development Guide - Technical setup and architecture details
• Contributors - People who have helped build Youtarr

Screenshots

Click to view screenshots

Channel Management (using "Dark Modern" theme)

Video Browser (using "Playful (Classic)" theme)

Configuration (using "Bold Flat" theme)

Download Manager (Dark Modern)

Individual Video Modal (Playful Classic)

Search for videos on YouTube from in-app (Bold Flat)

Responsive for mobile (Bold Flat)

Legal Disclaimer

Youtarr is not affiliated with YouTube or Plex. Users are responsible for ensuring their use complies with YouTube's Terms of Service and applicable copyright laws. This tool is intended for personal use with content you have the right to download.

License

Licensed under the ISC License. See LICENSE.md for details.