yt-downloader

Download a single YouTube video through an isolated Mullvad WireGuard tunnel.

Built as the video equivalent of music-gatherer's download phase: the only thing that talks to YouTube is the download command, and when a WireGuard config is configured it re-runs itself inside a dedicated network namespace whose only egress is the tunnel — so YouTube never sees your home IP. Everything else on your machine stays on the normal network.

Install

pip install -e .

Requires yt-dlp (pulled in automatically) and ffmpeg (used to mux separate video + audio streams into a single file).

Usage

yt-downloader init                 # write a starter config
yt-downloader download <url>       # download one video (auto-wraps into the VPN)
yt-downloader vpn up               # create the namespace + bring the tunnel up (sudo)
yt-downloader vpn status           # handshake time, routes, DNS
yt-downloader vpn down             # tear it all down

Download options:

yt-downloader download <url> -q 720                 # quality preset
yt-downloader download <url> -q best                # best video+audio (default)
yt-downloader download <url> -q audio               # audio only (no muxing needed)
yt-downloader download <url> -q 1080 -o ~/Videos    # custom output dir
yt-downloader download <url> -f 'bestvideo[height<=480]+bestaudio'   # raw yt-dlp format

Quality presets: best, 1080, 720, 480, audio. The -f/--format flag takes any yt-dlp format string and overrides the preset.

Downloads through a Mullvad VPN

By default downloads go through your normal connection. To route only the yt-dlp traffic through a WireGuard (Mullvad) tunnel, give the tool a WireGuard config:

[vpn]
wireguard = "~/.config/yt-downloader/mullvad.conf"   # Mullvad .conf
# namespace = "mullvad"   # optional: network namespace name
# interface = "mv0"       # optional: WireGuard interface name

When set, yt-downloader download re-runs itself inside a dedicated network namespace whose only egress is the WireGuard tunnel. The namespace has no fallback route, so a dead tunnel means a failed download, never a leak. Bring-up is automatic (ensure_up); use yt-downloader vpn up/down/status to manage it by hand.

It uses a Mullvad .conf ([Interface] + [Peer]), which you get from mullvad.net; the private key is copied into /etc/wireguard/mv0.conf.

Requirements: Linux, wireguard-tools + iproute2, and sudo. Interactive runs prompt for the sudo password once; for unattended runs add passwordless sudo entries:

# /etc/sudoers.d/yt-downloader   (run: sudo visudo -f /etc/sudoers.d/yt-downloader)
magerbeton ALL=(root) NOPASSWD: /usr/bin/ip, /usr/bin/wg, /usr/bin/wg-quick, \
  /usr/sbin/iptables, /usr/sbin/sysctl, /bin/mkdir, /bin/rm, /bin/chmod, /bin/sh

The download process drops back to your user inside the namespace, so downloaded files stay owned by you.

Bot-check mitigation

YouTube sometimes challenges downloads. Like music-gatherer, you can pass your browser cookies to yt-dlp:

[download]
# cookies_file = "/path/to/cookies.txt"
# cookies_from_browser = "firefox"   # e.g. chromium, firefox, safari

Configuration

See yt_downloader.toml after init for the full template (~/.config/yt-downloader/).

[download]
out = "~/Videos/yt-downloader"   # where videos land
quality = "best"                 # best | 1080 | 720 | 480 | audio
# format = ""                    # raw yt-dlp -f string, overrides quality

[vpn]
# wireguard = "~/.config/yt-downloader/mullvad.conf"
# namespace = "mullvad"
# interface = "mv0"

3.6 KiB Raw Blame History