How to Properly Configure and Use yt-dlp in n8n (Docker Version)

This tutorial guides you through permanently installing yt-dlp in an n8n instance running in Docker, and configuring cookie files to bypass login verification and anti-bot measures on platforms like YouTube and Bilibili.

Workflow automation illustration

---

📌 Why Is This So Complex?

By default, n8n runs in a “clean” Docker container. Any tools you install on the host server (like yt-dlp) are not accessible inside the n8n container. Therefore, we must build a custom n8n image that includes yt-dlp as part of the n8n environment.

Docker container isolation - showing the relationship between host machine and containers

---

🚀 Phase 1: Permanently Install yt-dlp in n8n

We will use docker-compose and a Dockerfile to build an n8n image containing yt-dlp and its dependencies (Python, ffmpeg).

Step 1: Create n8n Deployment Directory

On your server, create a new directory to store your configuration files.

# For example, create a directory named n8n-custom under /root/
mkdir /root/n8n-custom
cd /root/n8n-custom

---

Step 2: Create Dockerfile

In the /root/n8n-custom directory, create a file named Dockerfile.

nano Dockerfile

Paste the following content into the file. This configuration is based on Alpine Linux (the foundation of the official n8n image).

# -----------------------------------------------
# Custom n8n Dockerfile (Alpine Version)
# -----------------------------------------------

# 1. Use the official n8n image as base
FROM n8nio/n8n:latest

# 2. Switch to root user to install software
USER root

# 3. Use apk (Alpine's package manager) to install dependencies
#    We need python3, py3-pip, and ffmpeg (crucial for audio/video processing)
RUN apk update && \
    apk add python3 py3-pip ffmpeg && \
    rm -rf /var/cache/apk/*

# 4. Install yt-dlp using pip
#    We use --break-system-packages to bypass Alpine's system protection
RUN pip3 install yt-dlp --break-system-packages

# 5. Switch back to n8n's default secure user
USER node

Dockerfile code editing illustration

---

Step 3: Create docker-compose.yml

In the same directory, create a docker-compose.yml file.

nano docker-compose.yml

Paste the following content into the file.

version: '3.8'

services:
  n8n:
    # Key: Don't use 'image:', but 'build: .'
    # This tells Docker to build the image using the Dockerfile in the current directory
    build: .

    # Keep your preferred container name and port
    container_name: n8n_custom_service
    ports:
      - "9999:5678"

    # Key: Persist n8n data to the host machine
    volumes:
      - n8n_data_custom:/home/node/.n8n

    # (Optional) Set your Nginx reverse proxy URL
    environment:
      - N8N_PUBLIC_URL=https://n8n.your-domain.com
      - N8N_PROTOCOL=https
      - TZ=Asia/Shanghai
    restart: unless-stopped

volumes:
  # Define a Docker volume to safely store your data
  n8n_data_custom:

---

Step 4: Build and Start

In the /root/n8n-custom directory, run docker-compose.

docker-compose up -d --build

Docker will begin building your new image (this may take a few minutes), then start n8n.

Docker build process illustration

---

🍪 Phase 2: Configure Cookies to Bypass Verification

When yt-dlp accesses YouTube or Bilibili, it may fail due to bot detection on the server (such as “412 Precondition Failed” or “Sign in to confirm”). We must provide cookies.

Step 1: Obtain Cookie Files Locally

1. On your local computer (not the server), install a cookie export extension in Chrome/Firefox (e.g., Get cookies.txt)
2. Log in to youtube.com, click the extension icon, export cookies, and save as youtube_cookies.txt
3. Log in to bilibili.com, click the extension icon, export cookies, and save as bilibili_cookies.txt

Browser cookie export extension illustration

---

Step 2: Upload Cookies to n8n Data Volume

You need to upload these two .txt files to n8n’s persistent data directory.

2.1 Find the Volume Path

Based on our docker-compose.yml, the volume name is n8n_data_custom. Since your directory is n8n-custom, the actual Docker volume name might be n8n-custom_n8n_data_custom.

# Run this command to find the exact path on the host machine
docker volume inspect n8n-custom_n8n_data_custom | grep Mountpoint

You’ll get a path like: /var/lib/docker/volumes/n8n-custom_n8n_data_custom/_data

2.2 Create and Paste Cookie Content

Use nano with the path you found in the previous step to create files and paste cookie content.

# Create YouTube Cookie
nano /var/lib/docker/volumes/n8n-custom_n8n_data_custom/_data/youtube_cookies.txt
# (Paste content, save, exit)

# Create Bilibili Cookie
nano /var/lib/docker/volumes/n8n-custom_n8n_data_custom/_data/bilibili_cookies.txt
# (Paste content, save, exit)

---

Step 3: ⚠️ Fix Cookie File Permissions (Critical!)

The files you just created are owned by the root user. The node user inside the n8n container doesn’t have permission to read (or write) them, which will cause Permission denied errors.

We must change the ownership of these files inside the container.

# Force execute chown (change owner) as root user inside the container
docker exec --user root n8n_custom_service chown node:node /home/node/.n8n/youtube_cookies.txt
docker exec --user root n8n_custom_service chown node:node /home/node/.n8n/bilibili_cookies.txt

File permission fix illustration

---

🎯 Phase 3: Use yt-dlp in n8n

Everything is now ready.

Step 1: Find the Absolute Path of yt-dlp

Since we installed via Dockerfile, we need to know its exact path.

docker exec n8n_custom_service which yt-dlp

It will most likely return: /usr/bin/yt-dlp

---

Step 2: Use in “Execute Command” Node

In your n8n workflow, add an Execute Command node. In the Command field, you must use the absolute path and corresponding cookies.

n8n workflow configuration example

YouTube Example (Check Subtitles):

/usr/bin/yt-dlp --cookies /home/node/.n8n/youtube_cookies.txt --list-subs "https://www.youtube.com/watch?v=EXAMPLE_VIDEO_ID"

Bilibili Example (Check Subtitles):

/usr/bin/yt-dlp --cookies /home/node/.n8n/bilibili_cookies.txt --list-subs "https://www.bilibili.com/video/EXAMPLE_VIDEO_ID"

---

🎊 Common Commands Reference

Download Video (Best Quality)

/usr/bin/yt-dlp --cookies /home/node/.n8n/youtube_cookies.txt -f "bestvideo+bestaudio" "VIDEO_URL" -o "/home/node/.n8n/downloads/%(title)s.%(ext)s"

Download Audio Only

/usr/bin/yt-dlp --cookies /home/node/.n8n/youtube_cookies.txt -x --audio-format mp3 "VIDEO_URL" -o "/home/node/.n8n/downloads/%(title)s.%(ext)s"

Download Subtitles

/usr/bin/yt-dlp --cookies /home/node/.n8n/youtube_cookies.txt --write-subs --sub-lang en "VIDEO_URL"

---

🔧 Troubleshooting

Issue 1: Permission denied

Solution: Make sure you’ve executed the chown command to fix cookie file permissions.

Issue 2: yt-dlp: command not found

Solution: Make sure to use the absolute path /usr/bin/yt-dlp, not just yt-dlp.

Issue 3: 412 Precondition Failed

Solution: Cookies may have expired, you need to export and upload new cookie files.

---

✅ Summary

• ✅ Built a custom n8n Docker image containing yt-dlp
• ✅ Configured cookie files for YouTube and Bilibili
• ✅ Fixed file permission issues
• ✅ Successfully used yt-dlp in n8n workflows

Your n8n is now fully configured and ready to use yt-dlp reliably! 🎉

---

📚 References

• n8n Official Documentation
• yt-dlp GitHub Repository
• Docker Documentation
• Alpine Linux Package Management