Skip to content

YouTubeDL Material in Docker on a Synology NAS

Last updated on 4 December 2023

Please note if you are using DSM7.2 or higher you should use the Container Manager version of this guide from the menu.
This guide has reached the end of its updates as most people are now on the latest DSM update - This guide is correct as of 08/12/2023 however no further updates will be added.
Removed docker compose section as rarely used18/07/2023
changed image to nightly as this receives the most recent bug fixes and improvements04/12/2023
Historic updates now at the end of the guide.

What is YouTubeDL Material?

YouTubeDL Material is nice web front end for YoutubeDL, This is a tool that is used to download video from YouTube and many other sites. This is useful for if you want copies of videos to watch locally offline or if you like to hoard entire channels!

Let’s Begin

In this guide I am going to take you through the steps to get YoutubeDL Material up and running in Docker on your Synology NAS

In order for you to successfully use this guide please complete the two steps below first.

Downloading the Container

Open up Docker within DSM and navigate to the ‘Registry’ tab and search for ‘tzahi12345’ in the keyword box.

Within the results right click and download the top result ‘, When it asks which version number to download select ‘nightly‘ as this has the most recent updates for this container.

Please note the screenshot shows latest I will change this shortly to nightly

Setting up the container

Now we have downloaded the image and got hold of our user IDs we can move onto the next stage.

Go back into Docker and click on the ‘Image’ tab, in the list of your containers select the image, and click on ‘Launch’

The first screen will ask how you want to set up the Docker network, we are going to use the ‘bridge’ network allowing us to amend ports later.

General Settings

Next you will be greeted with the General Settings screen, this is where you can start specifying some of your preferences.

You can change the name of the container to anything you like, and you may want to enable Auto Restart as this will ensure the container starts automatically if you reboot your NAS.

You will also notice a Configure capabilities button — don’t change anything in here!

Next up we are going to click on the ‘Advanced Settings’ button, this will take you to a new window with a number of tabs which we are going to work through.


Next we are going to set up a couple of environment variables that docker will use to allow the container access to our files and folders.

Click the Add button, and fill in the following details as per the table/screenshot, you will need to do one at a time.

UIDThe UID you obtained in the user setup guide
GIDThe GID you obtained in the user setup guide
The default downloader can also be changed in the preferences

You do not need to set up anything on these tabs.

Press ‘Save’ to go back to the initial setup screen, then press ‘Next’

Port Settings

On this screen we are going to specify port 9998 to access YouTubeDL, this is in line with the Environment Variable set earlier. You will need to change BOTH the Local Port and the Container Port (we don’t normally do this)

Volume Settings

Where you store your downloaded videos can be changed based on your own preferences, I am basing this guide on the overall media setup and folder structure from our other guides.

Create a ‘youtube’ folder in /data/media and then add 4 subfolders

  • audio
  • subscriptions
  • users
  • video
Folder structure as per the screenshot

We can now move onto the volume tab in which we will be specifying the directories where YoutubeDL will store its configuration files and where the video downloads will be stored.

Click on Add Folder, click on the ‘docker’ share and create a new sub-folder called ‘youtubedl’ click on this folder and click ‘select’

We now need to repeat this process adding the folders below one at a time. Your path settings should look like the table/screenshot below.

File/FolderMount path

Click Next to move to the final screen.


You have now completed the setup of the container.

You will be shown an overall summary of the settings we have specified, this is a good time to double-check everything is correct. Finally, click on Done and the container should start to boot.

You should now be able to access the web interface via the IP of your NAS followed by the port 9998


You can use the main screen to download individual videos by pasting the URL and selecting the quality, or if you want to add subscriptions to specific channels use the menu on the left.

I recommend going into the advanced settings and amending the downloader to ‘yt-dlp’ if you have any issues pulling videos.

Historic UpdatesDate
New guide published05/03/2022
Small amendment made to the environment variables to specify the use of a local database10/05/2022
Updated with DSM7.1 Steps and Screenshots23/06/2022
Changes to ‘latest’ image and update steps09/07/2022
Added new port settings and Docker Bridge Network23/07/2022
Fixed a rogue old image for the ports section use ports 9998 on both sides!08/09/2022
Removed the default downloader so you can select one from the settings after startup.26/01/2023
Compose version number removed and small wording amendments09/04/2023
Amended the path to save the compose file – this is for security, so the container has no access to the file contents.14/04/2023
Historic Updates

Buy Me a Coffee or a Beer

If you have found my site useful please consider pinging me a tip as it helps cover the cost of running things or just lets me get the odd beverage. Plus 10% goes to the devs of the apps I do guides for every year.

Published inDockerMedia Management 7.1Synology


    • Dr_Frankenstein Dr_Frankenstein

      Hey, yes the tool should be working just fine, double-check your settings for the UID and GID to ensure the container can write to the filesystem. Also, if not already in the settings > advanced make sure you are using yt-dlp.

      • Omg, I was in auto pilot when I created it and instead of change UID and GID I created new fields PUID and PGID… thank you for your reply and for the guides.

  1. Jamie Jamie

    So, I have it all set up as specced (with my own variables, of course), and it seems to be running:

    backend@1.0.0 start
    pm2-runtime –raw pm2.config.js
    2022-09-01T22:20:00: PM2 log: Launching in no daemon mode
    2022-09-01T22:20:00: PM2 log: [Watch] Start watching YoutubeDL-Material
    2022-09-01T22:20:00: PM2 log: App [YoutubeDL-Material:0] starting in -fork mode-
    2022-09-01T22:20:00: PM2 log: App [YoutubeDL-Material:0] online
    2022-09-01T22:20:20.847Z INFO: Config items set using ENV variables.
    2022-09-01T22:20:21.365Z INFO: YoutubeDL-Material v4.3 started on PORT 9998

    I’ve checked, and port 9998 is listening, however when attempting to connect, I get a “site cannot be reached” error in the browser. Synology firewall isn’t active, so that’s not an issue (as demonstrated here):

    C:\Program Files (x86)\Nmap>ncat -zv 9998
    Ncat: Version 7.92 ( )
    Ncat: Connected to
    Ncat: 0 bytes sent, 0 bytes received in 0.01 seconds.

    I switched to the default network bridge my Sonarr and NZBGet containers are using, as well as tried it with the root user, with the same result.

    Any thoughts? Thanks!

  2. Louis Didier Louis Didier

    Hi Dr. Frank,
    I installed youtubedl and it works great. However, I am using it to record a live radio station. Not 100% functional to my needs. I cant for example stop the recording unless I delete the part of the mp3 from the audio folder nor I can schedule a recording. I tried clue/streamripper docker but it does not process https links correctly since my radio station streams in mp3 with https. Do you know any docker container that can perform such thing? Thank you in advance for all your hard work and your time.

    • Dr_Frankenstein Dr_Frankenstein

      I don’t think it’s dead – had some translations pulled into it last month. It still works fine.

  3. Gareth Blades Gareth Blades

    2022-04-02T18:51:48.864Z INFO: Cannot find config file. Creating one with default values…
    2022-04-02T18:51:48.897Z INFO: Beginning migration: 4.1->4.2+
    2022-04-02T18:51:48.906Z ERROR: EACCES: permission denied, scandir ‘audio/’
    2022-04-02T18:51:48.906Z ERROR: Migration failed: 4.1->4.2+
    2022-04-02T18:51:48.907Z INFO: Beginning migration: 4.2->4.3+
    2022-04-02T18:51:48.918Z INFO: 4.2->4.3+ migration complete!
    2022-04-02T18:51:49.293Z INFO: Found new update for youtube-dl. Updating binary…
    2022-04-02T18:51:50.763Z INFO: YoutubeDL-Material v4.2 started on PORT 17442
    2022-04-02T19:00:26.259Z ERROR: ERROR: Cannot write metadata to JSON file video/CNCF Kubernetes and Cloud Native Associate Certification Course (KCNA) – Pass the Exam!.info.json

    I setup the mounts as per your guide

    • Dr_Frankenstein Dr_Frankenstein

      Hey, it looks like it is failing to get permission to write to your folders, double check you set the UID and GID correctly as it can be easy to put them the wrong way around.

      • Gareth Blades Gareth Blades

        Yes they are set correctly. These are the detail I got and I set the uid and gid details the same.
        uid=1026(gblades) gid=100(users) groups=100(users),101(administrators)
        I have a calibre server running as the same user without issues. The only difference is the YouTube docker image is set to access a volume outside of /docker but I can’t imagine that would be an issue

        • Dr_Frankenstein Dr_Frankenstein

          Sorry I completely missed your reply, make sure the user has write permissions. If that fails try deleting the YouTubedl image and re downloading it just in case there is an issue with it.

      • Gareth Blades Gareth Blades

        I’m using NASInternal/Media/youtube/audio as one of the paths as an example. No spaces in any names. I don’t think capitals would be an issue but I remember reading something about it. Probably just to avoid issues with case sensitivity in Linux compared to windows.
        I’ll have a play and setup new file paths to see if I can get it working on Monday. Thanks

    • Dr_Frankenstein Dr_Frankenstein

      I know this is now months later but – Amit reached out, and we spotted that I have a rogue image in this guide! Use Port 9998 on both the Local AND Container ports!!.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed. – writing Synology Docker Guides since 2016 – Join My Discord!