# Youtarr: a self-hosted YouTube downloader that mirrors playlists into Plex, Jellyfin and Emby

> Youtarr is a Docker-only web app that subscribes to YouTube channels and playlists, downloads them with yt-dlp, and writes media-server metadata. It is for people who already run a media server and want channel archives inside it, not a general purpose downloader.

**DialmasterOrg/Youtarr** — Self-hosted web app that automates downloading, organizing, and scheduling YouTube channel content with support for Plex, Kodi, Emby and Jellyfin

- Repository: https://github.com/DialmasterOrg/Youtarr
- Website: https://youtarr.com
- Stars: 1,690 · Forks: 77
- Language: TypeScript
- License: ISC
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/dialmasterorg-youtarr

## What Youtarr is for, and who it is not for

Youtarr solves a narrow problem: getting YouTube channel and playlist content into a media server library without manual downloads. The README frames it around four uses, no ads or tracking, offline viewing, archiving content before it is deleted or made private, and curated family libraries. The feature list backs that up. Channels are organised into per-channel folders with metadata and thumbnails, and channel grouping lets you split them into subfolders such as `__kids`, `__music` and `__news` so each becomes a separate media server library. That is the audience: someone with a Plex, Jellyfin, Emby or Kodi server who wants a YouTube section that behaves like the rest of the library.

The wrong audience is equally clear. If you want a command line downloader for a handful of videos, yt-dlp already does that and Youtarr adds a database, a scheduler and a web UI on top. If you want full-text search across subtitles, the README's own comparison doc lists transcript search as one of the axes where Youtarr, Pinchflat and Tube Archivist differ, which implies Youtarr is not the strongest there. The project also states plainly that it runs exclusively via Docker and that direct `npm start` or Node deployments are unsupported, so anyone who wants to run a Node service on a host without containers is out of scope.

## How the download pipeline and metadata flow work

The architecture visible in the repository is a Node backend plus a React frontend, with MariaDB underneath and yt-dlp doing the actual fetching. The Dockerfile installs `ffmpeg`, `atomicparsley` and `python3` into the runtime image, which tells you what the pipeline needs: ffmpeg for muxing and conversion, atomicparsley for writing metadata into MP4 files, and Python because yt-dlp is a Python program. The same Dockerfile installs `apprise` and `curl-cffi` into `/opt` as separate Python targets. The comment next to the curl-cffi install explains why: yt-dlp wants an impersonation target for YouTube subtitle requests, and the zipimport binary does not bundle one.

On top of that pipeline sit the features that make it a library tool rather than a downloader. Downloads produce NFO files, poster images and embedded MP4 metadata. Playlist subscriptions are mirrored into Plex, Jellyfin and Emby as native playlists, and a universal `.m3u` file is written for anything else. Watch status flows the other way: Youtarr pulls per-video watched state from Plex, Jellyfin and Emby for every user on the server, shows a Watched chip, and lets you filter by watched or unwatched. The README is explicit that this is one-way and that Youtarr never writes back to your servers. Scheduling is cron-based, and auto-cleanup can remove videos by age, free space or watched state, with dry-run previews and per-video and per-channel protection.

## Installing Youtarr with docker-compose and running a first download

The Quick Start section lists Docker, Docker Compose, Git and a Bash shell (Git Bash on Windows) as prerequisites, and points at the Installation Guide for install methods and initial setup. The repository ships `start.sh` and `stop.sh`, plus `docker-compose.yml`, `docker-compose.arm.yml`, `docker-compose.dev.yml` and `docker-compose.external-db.yml`. The `.env.example` file is the configuration surface, and it says to copy it to `.env` before configuring. The one variable marked required is the host directory where videos land:

```bash
cp .env.example .env
# YOUTUBE_OUTPUT_DIR is the only required setting
YOUTUBE_OUTPUT_DIR=./downloads
```

The example file notes that this path must exist on the host before starting the containers, and that after editing `.env` you must fully restart the containers, either with `./stop.sh` then `./start.sh`, or with `docker compose down` then `docker compose up -d`. The web interface port is worth reading carefully: the container listens on 3011, the host port is set by `YOUTARR_HOST_PORT` and defaults to 3087, and the start scripts print and poll the matching setup URL if you change it.

If you run the container as a non-root user, the compose file comments give the setup explicitly. Set `YOUTARR_UID` and `YOUTARR_GID`, and create and chown the directories first, because Docker will create them as root if they do not exist:

```bash
mkdir -p config jobs server/images /path/to/youtube_videos
sudo chown -R 1000:1000 config jobs server/images /path/to/youtube_videos
```

Once the stack is up, the first real use is a channel subscription. The README describes subscribing to a channel and letting Youtarr auto-download new videos, shorts and streams with per-tab controls, and it describes a Find Channels on YouTube page where a click subscribes. Manually pasted URLs are pre-validated with a metadata preview before downloading, which is the safer path for a first test. The REST API is documented at `http://localhost:3087/swagger` if you would rather script it, though the README does not give a worked API example.

## The MariaDB volume is the part most likely to bite you

The README's database note is unusually blunt, and it is the strongest signal about where this project causes pain. 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, the project says this can be risky for MariaDB schema migrations. The symptoms it names are specific: `Table ... doesn't exist in engine` or `Incorrect information in file`. The compose file repeats the warning, calling out Docker Desktop on Windows and macOS, ARM hosts, and some NAS filesystems, and points to `docker-compose.arm.yml` or `scripts/migrate-to-named-volume.sh` as remedies.

This is a real adoption cost, not a footnote. It means the install method you choose on day one determines how painful future upgrades are, and that the difference between `./start.sh` and `docker compose up -d` is not cosmetic. If you are on Unraid, a Synology NAS or an ARM board, read the database doc before the first start rather than after the first failed migration. The project offers a migration path for existing bind-mounted installs, which is the honest thing to do, but it exists because people hit this.

## Youtarr vs Pinchflat: two answers to the same question

The README states that Youtarr predates Pinchflat, with first commits in May 2023 against January 2024, that the two arrived at similar solutions independently, and that they have evolved in parallel. That is an unusually candid framing, and it sets up the real difference: the two projects share a premise (subscribe to a channel, download with yt-dlp, serve it to a media server) and diverge on what they build around it.

The repository's own comparison doc lists the axes where Youtarr, Pinchflat and Tube Archivist differ: Plex integration, in-app playback, watch-status tracking, content ratings, REST API, filename templating and transcript search. Read that list as a map of Youtarr's bets. Watch-status sync pulls watched state from every user on your Plex, Jellyfin or Emby server and lets you filter and auto-clean on it. Content ratings are normalised to media-server values like `G`, `PG`, `PG-13`, `R`, `NC-17` and `TV-*`, can be set per download, via channel defaults, or derived from yt-dlp metadata, and can drive automated policies. In-app playback means you can click a thumbnail and stream in the browser without any media server at all. A REST API with Swagger docs targets people who want to automate. If none of those matter to you and you only want files on disk with sensible names, the comparison doc is the honest place to find out which project matches, because filename templating is listed as a point of difference and Youtarr's README does not describe a templating system.

## Licence, maintenance and what an upgrade actually costs

Youtarr is ISC licensed, which is a permissive licence in the same family as MIT and BSD, and the repository carries `LICENSE.md`. ISC imposes essentially no conditions beyond retaining the copyright notice and permission text, so redistributing or modifying it inside a commercial product is not the obstacle. This is not legal advice, and if you are bundling it into something you ship, read `LICENSE.md` and the `SECURITY.md` file yourself.

The maintenance picture from the repository metadata: the last push was on 2026-09-09, and releases v1.81.0, v1.81.1 and v1.82.0 landed between 2026-08-28 and 2026-09-08, while `package.json` shows version 1.82.1. The project is not archived. That cadence matters for upgrade cost because of the yt-dlp dependency: YouTube changes break extractors, and a downloader that is not updated will stop working regardless of how good its UI is. Youtarr bundles yt-dlp and pins supporting Python packages in the Dockerfile, so upgrades arrive as new images rather than as something you patch yourself.

The upgrade ritual is the containers plus the database. The `.env.example` file instructs a full restart after configuration changes, and the database notes describe schema migrations as the risky step. Practically, that means backing up the MariaDB volume before pulling a new image, and knowing whether your install is named-volume or bind-mounted before you do. The project also publishes a `dev-latest` image for unreleased features, which is documented in `docs/DEVELOPMENT.md`; running that on a library you care about is a choice, not a default.

## Conclusion

Adopt Youtarr if you already run Plex, Jellyfin or Emby and want channel and playlist archives to appear there with NFO files, posters and native playlists, and you are willing to run it through Docker Compose and keep the MariaDB volume healthy. Do not adopt it if you want a plain yt-dlp wrapper, a transcript search index, or a Node deployment without Docker; the README states direct npm start deployments are unsupported. Verify first that YOUTUBE_OUTPUT_DIR exists on the host with the ownership you intend, that your MariaDB data lives in a named volume rather than a bind mount, and that the container's published port is the one you expect, because the container listens on 3011 while the host port is configurable.

## FAQ

### Does Youtarr work without a media server?

Yes. The README lists Works Standalone as a reason to use it and states that in-app playback lets you stream downloaded videos in the browser with no media server required. Plex, Jellyfin and Emby integration adds playlist mirroring, watch-status sync and metadata for those servers.

### Can I install Youtarr without Docker?

No. The README states that Youtarr runs exclusively via Docker and that direct npm start or Node deployments are unsupported. The Quick Start prerequisites are Docker, Docker Compose, Git and a Bash shell.

### Does Youtarr write watch status back to Plex, Jellyfin or Emby?

No. The README describes watch status sync as one-way: Youtarr pulls per-video watched state from those servers for every user, but never writes back to them.

### Which port does the Youtarr web interface use?

The container listens on 3011. The host port is set by YOUTARR_HOST_PORT and defaults to 3087, and the .env.example notes that the start scripts print and poll the matching setup URL if you change it.

### What does Youtarr use to download videos?

The README states it is powered by yt-dlp, which handles YouTube integration and downloads. The Dockerfile also installs ffmpeg and atomicparsley in the runtime image for media processing and metadata embedding.

## Sources

- [DialmasterOrg/Youtarr on GitHub](https://github.com/DialmasterOrg/Youtarr)
- [License: ISC](https://github.com/DialmasterOrg/Youtarr/blob/main/LICENSE)
- [Project website](https://youtarr.com)
- [README](https://github.com/DialmasterOrg/Youtarr/blob/main/README.md)
- [Releases](https://github.com/DialmasterOrg/Youtarr/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/dialmasterorg-youtarr