Youtarr on Synology NAS

May 15, 2026 · View on GitHub

This guide provides Synology-specific installation instructions for Youtarr. Synology NAS devices running DSM 7+ can run Youtarr using Container Manager (Docker).

Why Synology Needs Special Instructions

The standard ./start.sh scripts work well on most Linux systems but may encounter issues on Synology DSM:

Shell compatibility differences in DSM
Directory permissions and path structures specific to Synology
Container Manager environment variables handling
Need for preset credentials in headless environments

This guide provides a manual configuration approach that works reliably on Synology.

Prerequisites

Synology NAS with DSM 7 or later
Container Manager installed (via Package Center)
Git Server installed (via Package Center) - optional but recommended
SSH access enabled (Control Panel → Terminal & SNMP)
User account with docker group membership

Installation Steps

Installation Overview: This guide walks you through installing Youtarr on Synology. The most critical step for Synology users is Step 4.5 where you must configure the database volume before first start. Unlike standard installations, Synology requires either named volumes or the LinuxServer MariaDB image to avoid permission issues.

Step 1: Enable SSH and Configure Docker Access

Enable SSH (if not already enabled):
- Open Control Panel → Terminal & SNMP
- Enable SSH service
- Note the port (default: 22)
Connect via SSH:
```
ssh yourusername@your-nas-ip
```
Add your user to the docker group (required for Docker access):
```
sudo synogroup --add docker yourusername
```

Log out and back in for group membership to take effect:

exit
# Then reconnect via SSH
ssh yourusername@your-nas-ip

Verify Docker access:

docker ps
# Should NOT show permission errors

Step 2: Choose Installation Location

Synology best practices recommend using /volume1/docker for containerized applications:

cd /volume1/docker

Alternative locations:

If you have multiple volumes, use /volumeX/docker where X is your volume number
For shared folders, you can use /volume1/some-shared-folder

Step 3: Clone Youtarr Repository

Option A: Using Git (recommended):

cd /volume1/docker
git clone https://github.com/DialmasterOrg/Youtarr.git
cd Youtarr

Option B: Manual Download:

Download the latest release from GitHub
Upload to your NAS via File Station
Extract to /volume1/docker/Youtarr

Step 4: Create Required Directories

The docker-compose.yml file expects certain directories to exist. Create them now:

cd /volume1/docker/Youtarr

# These directories are mounted by the containers
# Note: database directory is NOT needed - see Step 4.5 for database configuration
mkdir -p config
mkdir -p jobs
mkdir -p server/images

Create your video output directory (can be anywhere on your NAS):

# Example locations - choose what works for your setup:

# For Plex integration:
mkdir -p /volume1/media/youtube

# For Jellyfin/Emby integration:
mkdir -p /volume1/video/youtube

# For standalone use:
mkdir -p /volume1/docker/Youtarr/data/youtube

Important: Remember this path - you'll need it in the next step.

Step 4.5: Configure Database Volume (IMPORTANT!)

Critical for Synology: The official MariaDB Docker image runs as UID 999, which does not exist on Synology systems. Using a bind mount (like ./database:/var/lib/mysql) will fail with permission errors on Synology. You MUST configure the database volume before starting Youtarr for the first time.

Choose one of the following options:

Option 1: Named Volume (RECOMMENDED)

Named volumes are managed by Docker internally and avoid all permission issues. This is the simplest and most reliable option for Synology users.

Edit docker-compose.yml before first start:

cd /volume1/docker/Youtarr
vi docker-compose.yml

Tip: If you prefer nano and have installed it, use nano docker-compose.yml instead.

Make these changes:

Find the youtarr-db service's volumes: section (around line 39):

volumes:
  - ./database:/var/lib/mysql
  # Synology and Apple Silicon macOS users:
  # Uncomment the line below and comment out the line above to use named volume:
  # - youtarr-db-data:/var/lib/mysql

Change it to:

volumes:
  # - ./database:/var/lib/mysql
  # Synology and Apple Silicon macOS users:
  # Uncomment the line below and comment out the line above to use named volume:
  - youtarr-db-data:/var/lib/mysql

Find the volumes: section at the bottom of the file (around line 101):

# Synology and Apple Silicon macOS users:
# Uncomment the line below and comment out the line above to use named volume:
# volumes:
#   youtarr-db-data:

Change it to:

# Synology and Apple Silicon macOS users:
# Uncomment the line below and comment out the line above to use named volume:
volumes:
  youtarr-db-data:

Save the file:

In vi: Press Esc, type :wq, press Enter
In nano: Press Ctrl+O, Enter, then Ctrl+X

Benefits of named volumes:

No permission issues - Docker manages all permissions internally
Works perfectly with official MariaDB image
Portable across all platforms (Synology, QNAP, macOS, Linux)
No UID/GID configuration needed

Note about data location: The named volume data is stored by Docker in /volume/@docker/volumes/ on Synology. You can back it up using docker exec youtarr-db mysqldump (see Backup section).

Option 2: LinuxServer MariaDB with Bind Mount (ADVANCED)

If you need direct filesystem access to the database files (for easier backups or migrations), you can use the LinuxServer MariaDB image which respects PUID/PGID environment variables.

** This requires replacing the entire youtarr-db service definition in docker-compose.yml:**

1. Find your Synology user UID/GID

SSH into your NAS and run:

ssh <your-user>@<your-nas-ip>
id

You'll see something like:

uid=1026(youruser) gid=100(users) groups=100(users),...

In this example:

The PUID would be 1026
The PGID would be 100

cd /volume1/docker/Youtarr
vi docker-compose.yml

2. Replace the entire youtarr-db service (starting around line 17) with:

  youtarr-db:
    image: linuxserver/mariadb:latest
    container_name: youtarr-db
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD:-123qweasd}
      MYSQL_DATABASE: ${DB_NAME:-youtarr}
      MYSQL_TCP_PORT: ${DB_PORT:-3321}
      MYSQL_USER: ${DB_USER:-root}
      MYSQL_PASSWORD: ${DB_PASSWORD:-123qweasd}
      MYSQL_CHARSET: utf8mb4
      MYSQL_COLLATION: utf8mb4_unicode_ci
      # Replace these with your own UID/GID from the `id` command
      PUID: 1026 # Example: Synology default standard user
      PGID: 100  # Example: Synology default users group
    volumes:
      # Database files will be stored in ./database on the host
      - ./database:/config
    command: --port=${DB_PORT:-3321} --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-P", "${DB_PORT:-3321}", "-p${DB_PASSWORD:-123qweasd}"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s
    networks:
      - youtarr-network

3. Database directory: By default, Docker will automatically create the ./database directory (as root:root) the first time the container starts. The linuxserver/mariadb image will then chown /config to PUID:PGID during its init step, so in most cases you don’t need to do anything extra.

If you prefer to create it explicitly, or if you run into permission errors, you can do:

cd /volume1/docker/Youtarr
mkdir -p database
# Optional: If permissions are wrong, you can force ownership:
# chown <your_uid>:<your_gid> database
# Eg: chown 1026:100 database

Use the same UID/GID here that you set as PUID/PGID in the compose file.

Important differences:

Uses linuxserver/mariadb image instead of official mariadb:10.3
Volume mount path is ./database:/config (NOT /var/lib/mysql)
PUID=1026 and PGID=100 match typical Synology user permissions
- Find your DSM user’s UID/GID by SSHing into the NAS and running id.
This image respects those UID/GID settings and will chown the /config directory on startup.

When to use this option:

You need to access database files directly from the host
You're migrating from another system with existing database files
You want simpler backups via file copy instead of mysqldump

Drawbacks:

More complex configuration
Different image from official documentation
Slightly different file structure inside container

After configuring the database, proceed to Step 5 to configure environment variables.

Step 5: Configure Environment Variables

Create .env file

Youtarr includes a .env.example template that you can use as a starting point:

cd /volume1/docker/Youtarr
cp .env.example .env
vi .env

Tip: Synology DSM ships with the BusyBox vi editor. If you have installed nano separately and prefer it, you can run nano .env instead of vi .env.

Edit the file to configure your settings. At minimum, set the YOUTUBE_OUTPUT_DIR to match your video storage location:

# Required: Set this to your video output directory (adjust to match your path)
YOUTUBE_OUTPUT_DIR=/volume1/media/youtube

# Optional: Set initial admin credentials
# Use this when you want to skip the setup-token wizard
AUTH_PRESET_USERNAME=admin
AUTH_PRESET_PASSWORD=YourSecurePassword123

# Optional: Logging level (warn, info, debug)
LOG_LEVEL=info

The .env.example file contains detailed comments explaining each variable - refer to it for all available options.

Save the file:

Press Esc, then type :wq and press Enter (for vi)
If using nano, press Ctrl+O, Enter, then Ctrl+X

Security Note: Preset credentials via AUTH_PRESET persist. If you use them, you will not be able to change your username or password in the UI.

Verify .env file

cat .env

Ensure YOUTUBE_OUTPUT_DIR matches the directory you created in Step 4.

Note about config.json: You don't need to manually create or edit config/config.json:

If config.json doesn't exist, it will be auto-created on first startup with correct defaults
You can configure Plex and other settings later through the web UI

Step 6: Start Youtarr

⚠️ IMPORTANT: Before starting, ensure you completed Step 4.5 to configure the database volume! Skipping Step 4.5 will cause MariaDB to fail with permission errors on Synology.

Start the containers using docker compose:

Compose command on Synology: DSM 7 installs Docker Compose v2, which uses the space-separated syntax (docker compose). If your environment still uses the legacy v1 binary, substitute docker-compose in the examples below.

cd /volume1/docker/Youtarr
docker compose up -d

Monitor the startup:

# Check container status
docker compose ps

# View logs
docker compose logs -f

# Press Ctrl+C to exit log viewing

Expected output:

youtarr-db container should show as "healthy"
youtarr container should show as "running"

Known harmless messages:

IPv6 rate limiting warnings can be ignored
"Waiting for database" is normal during first startup

Step 7: Access Youtarr

Open your web browser and navigate to:

http://your-nas-ip:3087

First-time setup:

If you set AUTH_PRESET_USERNAME and AUTH_PRESET_PASSWORD in .env, log in with those credentials
If you didn't set credentials, you'll be prompted to create an admin account with the one-time token from docker compose logs youtarr or config/setup-token

After logging in:

Navigate to Configuration page
(Optional) Configure Plex integration if desired
Add your first YouTube channel subscription
Start downloading videos!

Synology-Specific Notes

Container Manager GUI (Alternative to SSH)

While SSH is recommended for initial setup, you can also manage Youtarr through Container Manager:

Open Container Manager from DSM Package Center
Go to Project tab
Click Create
Set project name: youtarr
Set path: /volume1/docker/Youtarr (or your chosen location/volume)
Upload or create docker-compose.yml

However, manual configuration via SSH is more reliable for environment variables and initial setup.

File Permissions

Youtarr runs as root by default inside the container, which should work with Synology's default permissions. If you encounter permission issues with the app container (not database):

First stop Youtarr, then:

1. Find your Synology user UID/GID

SSH into your NAS and run:

ssh <your-user>@<your-nas-ip>
id

You'll see something like:

uid=1026(youruser) gid=100(users) groups=100(users),...

In this example:

The PUID would be 1026
The PGID would be 100

2. Fix ownership for app directories

# Fix ownership for app directories only (from SSH)
cd /volume1/docker/Youtarr
# sudo chown -R <your uid>:<your gid> config jobs server
# Eg: sudo chown -R 1026:100 config jobs server

Set the UID/GID in your .env file using your UID/GID, example:

YOUTARR_UID=1026
YOUTARR_GID=100

Then restart Youtarr

Important: The YOUTARR_UID and YOUTARR_GID environment variables only affect the youtarr app container, not the database container.

If you're using named volumes (Step 4.5 Option 1), database permissions are handled automatically by Docker
If you're using linuxserver/mariadb (Step 4.5 Option 2), database permissions are controlled by the PUID and PGID settings in docker-compose.yml
If you have database permission errors with the official MariaDB image, see the "Database Permission Errors" section below

Network Access

Port Requirements:

3087: Web UI and API
MariaDB is only reachable inside the Docker network by default

Firewall:

Ensure port 3087 is accessible on your local network
For remote access, use Synology's reverse proxy or VPN (do not expose directly to internet)

Storage Locations

Recommended directory structure:

/volume1/docker/Youtarr/          # Application files
├── config/                        # Youtarr configuration
├── database/                      # MariaDB data
├── jobs/                          # Job processing data
├── server/                        # Server assets
└── .env                          # Environment variables

/volume1/media/youtube/           # Downloaded videos (example)

See YOUTARR_DOWNLOADS_FOLDER_STRUCTURE.md for structure of downloaded videos

Integration with Media Servers on Synology

Plex

If Plex runs on the same NAS, use your NAS's local IP address (e.g., 192.168.1.100)
Point Plex library to the same path as YOUTUBE_OUTPUT_DIR
Configure as "Other Videos" library type with "Personal Media" agent

Jellyfin

Install via Container Manager or Package Center
Add library as "Movies" type
Enable NFO metadata reader
Point to your YOUTUBE_OUTPUT_DIR

Emby

Similar to Jellyfin setup
Use NFO metadata format
Configure as Movies library

Updating Youtarr

To update Youtarr to the latest version:

cd /volume1/docker/Youtarr

# Pull latest code
git pull

# Pull latest Docker images and restart
docker compose pull
docker compose up -d

# View logs to verify update
docker compose logs -f

Stopping and Starting

Stop Youtarr:

cd /volume1/docker/Youtarr
docker compose down

Start Youtarr:

cd /volume1/docker/Youtarr
docker compose up -d

Restart Youtarr:

cd /volume1/docker/Youtarr
docker compose restart

Troubleshooting

"YOUTUBE_OUTPUT_DIR not set" Error

Symptom: Container fails to start with error about empty section between colons.

Solution:

Verify .env file exists: cat /volume1/docker/Youtarr/.env
Verify it contains: YOUTUBE_OUTPUT_DIR="/your/path"
Restart containers: docker compose down && docker compose up -d

"ffmpeg-location undefined does not exist" Error

Symptom: Logs show warnings about ffmpeg location.

Root Cause: This usually indicates YOUTUBE_OUTPUT_DIR was not properly set, causing yt-dlp to fail.

Solution:

Verify YOUTUBE_OUTPUT_DIR in .env file matches a real directory
Verify directory exists: ls -la /volume1/media/youtube
Check directory permissions: ls -ld /volume1/media/youtube
Restart containers: docker compose restart

"'NoneType' object has no attribute 'lower'" Error

Symptom: Videos fail to download with Python errors.

Root Cause: Missing or incorrect YOUTUBE_OUTPUT_DIR configuration.

Solution: Follow the steps in "YOUTUBE_OUTPUT_DIR not set" above.

"Bind mount failed" Errors

Symptom: Container won't start, logs show mount errors.

Solution:

cd /volume1/docker/Youtarr
mkdir -p database config jobs server/images
docker compose up -d

"Permission denied" on Docker Commands

Symptom: docker or docker compose commands fail with permission errors.

Solution:

# Add user to docker group (if not already done)
sudo synogroup --add docker yourusername

# IMPORTANT: Log out completely and reconnect
exit
# Reconnect via SSH

# Verify group membership
groups
# Should include "docker"

# Test Docker access
docker ps

Web Interface Not Accessible

Symptoms: Cannot reach http://your-nas-ip:3087

Troubleshooting steps:

Check container status:

docker compose ps
# Both containers should be running

Check logs for errors:
```
docker compose logs
```

Verify port is listening:

sudo netstat -tulpn | grep 3087
# Should show docker-proxy listening on port 3087

Check firewall:
- DSM: Control Panel → Security → Firewall
- Ensure port 3087 is allowed

Test from NAS itself:

curl http://localhost:3087
# Should return HTML content

Symptom: Browser shows "Initial setup required" and asks for a setup token.

Cause: Initial credentials have not been configured yet.

Solution A: Use the setup token:

cd /volume1/docker/Youtarr
docker compose logs youtarr | grep -A5 "initial setup required"

# Or read the token file directly:
cat config/setup-token

Paste the token into the setup wizard and create your admin account.

Solution B: Set preset credentials:

# Edit .env file
vi /volume1/docker/Youtarr/.env

# Add these lines:
AUTH_PRESET_USERNAME=admin
AUTH_PRESET_PASSWORD=YourSecurePassword123

# Restart to apply
docker compose down
docker compose up -d

Tip: If you prefer nano and have installed it, replace vi with nano in the command above. In vi, press Esc, type :wq, then press Enter to save and exit.

Database Connection Errors

Symptom: Logs show "Error: connect ECONNREFUSED" or database connection failures.

Solution:

Check database container health:

docker compose ps
# youtarr-db should show "healthy"

View database logs:
```
docker compose logs youtarr-db
```

Restart database:

docker compose restart youtarr-db
# Wait 30 seconds for health check
docker compose restart youtarr

If issues persist, reset database: WARNING: This deletes all data in your database!

If using host mounted database

docker compose down
rm -rf database/*
docker compose up -d

If using volume mounted database

docker compose down -v # Removes the named volume (defaults to youtarr-db-data)
docker compose up -d   # Recreates the volume and initializes a fresh database

Database Permission Errors or "Duplicate column name" Errors

Symptoms:

MariaDB container fails to start with permission errors (error 13)
"InnoDB: Operating system error number 13 in a file operation"
"Database error: Duplicate column name 'duration'" in web UI
Database corruption issues

Root Cause:

Most Synology failures are straight permission issues: the official MariaDB image runs as UID 999, which often lacks ownership rights on /volume1/... bind mounts. MariaDB can't even open the files and surfaces error 13. This is why Step 4.5 instructs you to configure database volumes BEFORE first start.
If you actually have a duplicate-column error (for example after restoring a database backup), all Youtarr migrations now check for existing schema and skip work they have already performed. A simple restart usually clears the error automatically; if not, drop the duplicate column manually (per the main Troubleshooting guide) and rerun.

If you already started Youtarr and are seeing permission errors:

Option A: Switch to Named Volume (Recommended - Fresh Start)

If you don't have important data yet or can re-add your channels:

Stop containers:

cd /volume1/docker/Youtarr
docker compose down

Follow Step 4.5 Option 1 to edit docker-compose.yml for named volumes

Remove failed bind mount data (optional cleanup):

# Only if you want to clean up the failed attempt
sudo rm -rf database

Start containers:
```
docker compose up -d
```

Option B: Switch to LinuxServer MariaDB (Advanced - Keep Bind Mount)

If you need bind mounts for some reason:

Stop containers:

cd /volume1/docker/Youtarr
docker compose down

Follow Step 4.5 Option 2 to replace the youtarr-db service with linuxserver/mariadb

Fix permissions on existing database directory:

sudo chown -R <your uid>:<your gid> database

Start containers:
```
docker compose up -d
```

Option C: Migrate Existing Data to Named Volume

If you have existing data in ./database/ that you want to preserve:

Backup your database first:

# Try to start just the database temporarily to dump data
docker compose up -d youtarr-db
sleep 30
docker exec youtarr-db mysqldump -u <db_user> -p'<db_password>' <db_name> > /volume1/backups/youtarr-backup.sql
# Replace <db_user>, <db_password>, and <db_name> with the values from your .env file (defaults: root / 123qweasd / youtarr).
docker compose down

Switch to named volume (follow Option A steps 1-2)
Start containers to initialize fresh database:
```
docker compose up -d
```

Restore your data:

# Wait for database to be healthy
sleep 30
docker exec -i youtarr-db mysql -u <db_user> -p'<db_password>' <db_name> < /volume1/backups/youtarr-backup.sql
# Replace <db_user>, <db_password>, and <db_name> with the values from your .env file.
docker compose restart youtarr

Prevention for new installations:

✅ Always follow Step 4.5 before starting Youtarr for the first time to avoid these issues entirely!

High CPU Usage

Symptom: NAS CPU usage spikes during video downloads.

Cause: yt-dlp and ffmpeg are CPU-intensive during video processing.

Solutions:

Schedule downloads during off-peak hours (configure via Youtarr UI)
Reduce concurrent download limits in Configuration
Lower video quality settings to reduce processing time
Disable SponsorBlock integration (if enabled)

Out of Disk Space

Symptom: Downloads fail, database errors, container issues.

Solution:

Check available space:
```
df -h /volume1
```
Enable automatic cleanup in Youtarr:
- Configuration → Automatic Video Removal
- Set age threshold (e.g., remove videos older than 90 days)
- Set free space threshold (e.g., maintain 100 GB free)

Manual cleanup:

# Find and remove old videos
find /volume1/media/youtube -name "*.mp4" -mtime +90 -delete

Backup and Restore

Backup Configuration and Database

# Create backup directory
mkdir -p /volume1/backups/youtarr

# Backup configuration
cp -r /volume1/docker/Youtarr/config /volume1/backups/youtarr/config-$(date +%Y%m%d)

# Backup database (with containers running).
# Replace <db_user>, <db_password>, and <db_name> with the values from your .env file.
docker exec youtarr-db mysqldump -u <db_user> -p'<db_password>' <db_name> > /volume1/backups/youtarr/database-$(date +%Y%m%d).sql

Optional file-level backups

Bind mount / linuxserver installs:

docker compose down
cp -r /volume1/docker/Youtarr/database /volume1/backups/youtarr/database-$(date +%Y%m%d)
docker compose up -d

Named volume installs (default volume name is youtarr-db-data; adjust if you changed it):

docker run --rm \
  -v youtarr-db-data:/var/lib/mysql \
  -v /volume1/backups/youtarr:/backup \
  busybox sh -c 'cd /var/lib/mysql && tar czf /backup/youtarr-db-$(date +%Y%m%d).tar.gz .'

Restore from Backup

Stop containers and restore configuration

cd /volume1/docker/Youtarr
docker compose down
rm -rf config
cp -r /volume1/backups/youtarr/config-YYYYMMDD config

Restore the database – choose the workflow that matches your setup:

From mysqldump (works everywhere):

docker compose up -d youtarr-db
sleep 30
docker exec -i youtarr-db mysql -u <db_user> -p'<db_password>' <db_name> < /volume1/backups/youtarr/database-YYYYMMDD.sql
docker compose restart youtarr

Bind mount / linuxserver installs:

rm -rf database
cp -r /volume1/backups/youtarr/database-YYYYMMDD database
docker compose up -d

Named volume installs:

docker compose down
docker volume rm youtarr-db-data
docker run --rm \
  -v youtarr-db-data:/var/lib/mysql \
  -v /volume1/backups/youtarr:/backup \
  busybox sh -c 'cd /var/lib/mysql && tar xzf /backup/youtarr-db-YYYYMMDD.tar.gz'
docker compose up -d

Replace youtarr-db-data if you customized the volume name.

Performance Optimization for Synology

Reduce Docker Logging Overhead

Large log files can impact performance. Limit log size:

# Edit docker-compose.yml
vi docker-compose.yml

Tip: Use Esc then :wq to save in vi. If you installed nano, you can run nano docker-compose.yml instead.

Add logging configuration to both services:

services:
  youtarr-db:
    # ... existing config ...
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

  youtarr:
    # ... existing config ...
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

Apply changes:

docker compose down && docker compose up -d

Use SSD Cache (If Available)

If your NAS has SSD cache:

Storage Manager → SSD Cache
Create read-write cache
Enable for volume containing Docker data

Schedule Downloads During Low-Activity Periods

Configure Youtarr's cron schedule for late night:

Configuration → Download Schedule
Example: 0 2 * * * (runs at 2 AM daily)

Uninstalling Youtarr

To completely remove Youtarr:

# Stop and remove containers
cd /volume1/docker/Youtarr
docker compose down -v

# Remove application files
cd /volume1/docker
rm -rf Youtarr

# Optional: Remove downloaded videos
# rm -rf /volume1/media/youtube

Additional Resources

Main Documentation: README.md
Docker Guide: DOCKER.md
Media Server Setup: MEDIA_SERVERS.md
General Troubleshooting: TROUBLESHOOTING.md
GitHub Issues: Report problems

Getting Help

If you encounter issues not covered in this guide:

Check the logs:
```
docker compose logs -f
```
Search existing issues: GitHub Issues
Create a new issue with:
- Your Synology model and DSM version
- Contents of .env file (redact passwords)
- Output of docker compose ps
- Relevant logs from docker compose logs