mikenye/youtube-dl

yt-dl - download videos many online video platforms

Note: As of 2022-01-05 updated to use yt-dlp

mikenye/youtube-dl

Multi Architecture Support

This image should pull and run on the following architectures: linux/amd64, linux/arm64/v8, linux/arm/v6, linux/arm/v7, linux/386, linux/ppc64le, linux/s390x.

Quick Start

NOTE: The docker command provided in this quick start is given as an example, and parameters should be adjusted to your needs.

It is suggested to configure an alias as follows (and place into your .bash_aliases file):

alias yt-dl='docker run \
                  --rm -i \
                  -e PGID=$(id -g) \
                  -e PUID=$(id -u) \
                  -v "$(pwd)":/workdir:rw \
                  ghcr.io/mikenye/docker-youtube-dl:latest'

HANDY HINT: After updating your .bash_aliases file, run source ~/.bash_aliases to make your changes live!

When run (eg: yt-dl <video_url>), it will download the video to the current working directory, and take any command line arguments that the normal youtube-dl binary would.

Running on Unraid

Unraid forum user Timmyx has written a fantastic guide to deploying this image on Unraid. The guide can be found here:

https://forums.unraid.net/topic/100256-youtube-dl-strategy/

Using a config file

To prevent having to specify many command line arguments every time you run youtube-dl, you may wish to have an external configuation file.

In order for the docker container to use the configuration file, it must be mapped through to the container.

docker run \
    --rm -i \
    -e PGID=$(id -g) \
    -e PUID=$(id -u) \
    -v /path/to/downloaded/videos:/workdir:rw \
    -v /path/to/yt-dlp.conf:/etc/yt-dlp.conf:ro \ 
    ghcr.io/mikenye/docker-youtube-dl:latest

Where:

/path/to/downloaded/videos is where youtube-dl will download videos to (use "$(pwd)" to downloade to current working directory.
/path/to/yt-dlp.conf is the path to your yt-dlp.conf file.

Authentication using `.netrc`

If you want to download videos that require authentication (or your youtube subscriptions for example, see below), it is recommended to use a .netrc file.

You can create a file with the following syntax:

machine youtube login USERNAME password PASSWORD

Where:

USERNAME is replaced with your youtube account username
PASSWORD is replaced with your youtube account password

You may need to disable some account security settings (such as '2-Step Verification' and 'Use your phone to sign in', so it is suggested to make a long, complex password (eg: 32 random characters).

This file can then be mapped through to the container as a .netrc file, eg:

docker run \
    --rm -i \
    -e PGID=$(id -g) \
    -e PUID=$(id -u) \
    -v /path/to/downloaded/videos:/workdir:rw \
    -v /path/to/youtube-dl.conf:/etc/youtube-dl.conf:ro \
    -v /path/to/netrc_file:/home/dockeruser/.netrc:ro
    ghcr.io/mikenye/docker-youtube-dl:latest

Configuration Files

Container Path	Permissions	Description
`/config/youtube-dl.conf`	`ro`	If this file exists at container startup, it is symlinked to `/etc/youtube-dl.conf` at container startup. The `youtube-dl` process will look in this location for a configuration file by default.
`/config/.netrc`	`ro`	If this file exists at container startup, it is symlinked to `/home/dockeruser/.netrc` at container startup. The `youtube-dl` process will look in this location for a .netrc file (if `--netrc` is specified on the command line or via a configuration file).
`/config/.cache`	`rw`	If this directory exists at container startup, it is symlinked to `/home/dockeruser/.cache/youtube-dl` at container startup. The `youtube-dl` process automatically uses this path for caching.

You can place any other configuration files within /config, and then specify them on the command line, eg: --batch-file /config/batch-file.conf.

Data Volumes

There are no data volumes explicity set in the Dockerfile, however:

Container Path	Permissions	Description
`/workdir`	rw	The `youtube-dl` process is executed with a working directory of `/workdir`. Thus, unless you override the output directory with the `--output` argument on the command line or via a configuration file, videos will end up in this directory.

Environment Variables

To customize some properties of the container, the following environment variables can be passed via the -e parameter (one for each variable). This paramater has the format <VARIABLE_NAME>=<VALUE>.

Variable	Description	Recommended Setting
`PGID`	The Group ID that the `youtube-dl` process will run as	`$(id -u)` for the current user's GID
`PUID`	The User ID that the `youtube-dl` process will run as	`$(id -g)` for the current user's UID
`UMASK`	Optional. Set's the umask for files created by `youtube-dl`
`UPDATE_YOUTUBE_DL`	Set to any value and `youtube-dl -U` will be run on container start

Ports

No port mappings are required for this container.

Scheduled download of youtube subscriptions

In order to perform a scheduled download of youtube subscriptions, it is recommended to use the following command to be executed via cron on a regular basis (eg: daily).

docker run \
    --rm
    -i
    --name youtube-dl-cron
    -e PGID=GID
    -e PUID=UID
    --cpus CPUS
    -v /path/to/netrc:/home/dockeruser/.netrc:ro
    -v /path/to/youtube/subscriptions:/workdir:rw
    -v /path/to/youtube-dl.conf:/etc/youtube-dl.conf:ro
    ghcr.io/mikenye/docker-youtube-dl:latest \
    :ytsubscriptions \
    --dateafter now-5days \
    --download-archive /workdir/.youtube-dl-archive \
    --cookies /workdir/.youtube-dl-cookiejar \
    --netrc \
    --limit-rate 5000 2>> /path/to/logs/youtube-dl.err >> /path/to/logs/youtube-dl.log

Where:

GID: a group ID to run as (if in a normal user's crontab, use $(id -g)
UID: a user ID to run as (if in a normal user's crontab, use $(id -u)
CPUS: the number of CPUs to constrain the docker container to. This may be required to prevent impacting system performance if transcoding takes place. If not, the --cpus argument can be completely omitted.
/path/to/netrc: the path to the file containing your youtube credentials, see above.
/path/to/youtube/subscriptions: the path where videos will be saved.
/path/to/youtube-dl.conf: the path to your youtube-dl.conf file, where settings such as output file naming, quality, etc can be determined.
/path/to/logs/youtube-dl.err: the path to the error log, if desired
/path/to/logs/youtube-dl.log: the path to the application log, if desired

Notes:

--rm is given so the container is destroyed when execution is finished. This will prevent your drive from slowly filling up with exited containers.
--name youtube-dl-cron is given so that multiple instances are not started by cron. In the event the previous container is still running, docker will simply exit with an error that the container name is already taken.
--dateafter now-5days is given to limit youtube-dl to only download recent videos. Feel free to adjust as required.
--limit-rate is given to prevent impacting your internet connection. Feel free to adjust as required.

In the example above, a configuration file is used. This allows us to easily add commands to select a specific quality, and name the videos with a specific format. For example, to download the videos into a format recognised by Plex, you could use the following:

-v
--ignore-errors
--no-overwrites
--continue
--no-post-overwrites
--add-metadata
--write-thumbnail
--playlist-reverse
--write-description
--write-info-json
--write-annotations
--format "best[height<=?1080]"
--fixup fix
--output '/workdir/%(uploader)s/%(uploader)s - %(upload_date)s - %(title)s - %(id)s.%(ext)s'

The above example config file will:

Ignore errors
Will not overwrite existing videos
Will continue downloading in the event a download is interrupted
Will download metadata and embed into the resulting video, so that Plex will be able to display this information
Will download oldest videos first, so videos can be sorted by "date added" in Plex
Will download the best quality up to a maximum of 1080p (prevent 4K downloads)
Will format videos with a separate folder for each uploader.

Docker Image Update

If the system on which the container runs doesn't provide a way to easily update the Docker image (eg: watchtower), simply pull the latest version of the container:

docker pull ghcr.io/mikenye/docker-youtube-dl:latest

Shell access

To get shell access to a running container, execute the following command:

docker exec -ti CONTAINER sh

Where CONTAINER is the name of the running container.

To start a container with a shell (instead of youtube-dl), execute the following command:

docker run --rm -ti --entrypoint=/bin/sh ghcr.io/mikenye/docker-youtube-dl:latest

Support or Contact

Having troubles with the container or have questions? Please create a new issue.

neilcronin/docker-youtube-dl

mikenye/youtube-dl

Table of Contents

Multi Architecture Support

Quick Start

Running on Unraid

Using a config file

Authentication using `.netrc`

Configuration Files

Data Volumes

Environment Variables

Ports

Scheduled download of youtube subscriptions

Docker Image Update

Shell access

Support or Contact

neilcronin/docker-youtube-dl

mikenye/youtube-dl

Table of Contents

Multi Architecture Support

Quick Start

Running on Unraid

Using a config file

Authentication using .netrc

Configuration Files

Data Volumes

Environment Variables

Ports

Scheduled download of youtube subscriptions

Docker Image Update

Shell access

Support or Contact

Authentication using `.netrc`