Skip to main content

Supercharging yt-dlp with aria2 for 16x Download Speeds

By default, yt-dlp relies on Python's single-threaded HTTP stream downloader, frequently choked by CDN rate limiters and single TCP socket buffer bottlenecks. Integrating aria2c as an external engine enables up to 16 parallel connections per video stream, saturating multi-gigabit connections.

1. Performance Benchmark: Native vs aria2

Why do video downloads crawl when your broadband speed is 500 Mbps or 1 Gbps? Video content delivery networks (CDNs) dynamically throttle single TCP stream speeds to conserve egress bandwidth. Splitting transfers into 16 discrete HTTP byte-range requests completely bypasses per-stream bandwidth caps:

Video Quality & Size yt-dlp Native (1 Stream) yt-dlp + aria2 (16 Connections) Speed Improvement
1080p 60fps (850 MB) 2m 45s (5.1 MB/s) 14s (60.7 MB/s) 11.8x Faster ⚡
4K UHD 60fps HDR (3.4 GB) 9m 12s (6.2 MB/s) 38s (89.5 MB/s) 14.5x Faster ⚡
8K 60fps AV1 (9.8 GB) 28m 40s (5.7 MB/s) 1m 48s (92.4 MB/s) 15.9x Faster ⚡

2. The Essential Command Line Arguments

To pass aria2c to yt-dlp on the command line, use the --downloader (or --external-downloader) parameter paired with --downloader-args:

yt-dlp --downloader aria2c --downloader-args "aria2c:-x 16 -s 16 -k 1M" "https://www.youtube.com/watch?v=VIDEO_ID"

Flag Anatomy & Technical Explanation:

  • --downloader aria2c: Tells yt-dlp to extract the signed stream URLs, cookies, and headers, then hand off the heavy payload download to aria2c.
  • aria2c:-x 16: Configures --max-connection-per-server=16 (maximum number of simultaneous TCP sockets to open against one CDN hostname).
  • aria2c:-s 16: Configures --split=16 (partitions the video file into 16 independent byte chunks downloaded simultaneously).
  • aria2c:-k 1M: Configures --min-split-size=1M (ensures segments are at least 1 Megabyte to prevent connection churn on small files).
  • aria2c:-j 4: Optional: Sets maximum concurrent active downloads when pulling playlists or multi-video queues.

⚡ Interactive yt-dlp + aria2 Command Generator

Configure your flags below to generate an optimized one-liner command:

yt-dlp --downloader aria2c --downloader-args "aria2c:-x 16 -s 16 -k 1M" -f "bestvideo+bestaudio/best" --merge-output-format mkv --embed-subs --embed-chapters "URL"

3. Advanced Production Recipes

Real-world CLI configurations for complex downloading workflows, playlists, proxies, and browser cookies:

A. Downloading Entire Playlists with Archive History

Download a complete channel or playlist without duplicate re-downloads, keeping a downloaded.txt archive ledger: 

yt-dlp --downloader aria2c \
  --downloader-args "aria2c:-x 16 -s 16 -k 1M -j 4" \
  --download-archive downloaded_archive.txt \
  -o "%(playlist_title)s/%(playlist_index)s - %(title)s.%(ext)s" \
  "https://www.youtube.com/playlist?list=PLAYLIST_ID"

B. Passing Browser Cookies to Bypass 403 Forbidden & Age-Gates

When downloading private, premium, or age-restricted videos, pass session cookies directly from your local browser. yt-dlp automatically translates session headers into aria2c request arguments: 

yt-dlp --cookies-from-browser chrome \
  --downloader aria2c \
  --downloader-args "aria2c:-x 16 -s 16 -k 1M" \
  "https://www.youtube.com/watch?v=VIDEO_ID"

C. Tunneling via SOCKS5 / HTTP Proxy

To bypass geo-restrictions or download through an encrypted VPS tunnel, supply the proxy URL to both yt-dlp and aria2: 

yt-dlp --proxy "socks5://127.0.0.1:1080" \
  --downloader aria2c \
  --downloader-args "aria2c:--all-proxy=http://127.0.0.1:1080 -x 16 -s 16" \
  "https://www.youtube.com/watch?v=VIDEO_ID"

4. Making aria2 the Permanent Default in yt-dlp

Instead of manually typing flags every time, create a global yt-dlp.conf file on your operating system:

Config File Directory Paths:

  • Windows: %APPDATA%\yt-dlp\config (e.g. C:\Users\<You>\AppData\Roaming\yt-dlp\config)
  • Linux / macOS: ~/.config/yt-dlp/config or /etc/yt-dlp.conf
  • Android (Termux): ~/.config/yt-dlp/config

Paste the following production-optimized configuration into your config file:

# Production yt-dlp.conf 
# 1. Use aria2 as external multi-connection engine
--downloader aria2c
--downloader-args "aria2c:-x 16 -s 16 -k 1M --retry-wait=3 --max-tries=5"

# 2. Automatically select highest quality streams and remux to MKV
-f "bestvideo+bestaudio/best"
--merge-output-format mkv

# 3. Embed artwork, chapters, and metadata
--embed-chapters
--embed-metadata
--embed-thumbnail

# 4. Standard clean output naming
-o "~/Downloads/Videos/%(title)s [%(id)s].%(ext)s"

5. Troubleshooting & FAQs

Common issues encountered when pairing aria2 with yt-dlp and how to resolve them:

Q1: "ERROR: aria2c exited with code 1 / 3 / 9" or "HTTP 403 Forbidden"

Cause: YouTube video CDN links use temporary signed tokens that expire or bind to a specific User-Agent. If aria2 sends an incompatible User-Agent, the CDN drops the connection.
Solution: Ensure yt-dlp forwards headers properly, or reduce connections to 8: --downloader-args "aria2c:-x 8 -s 8 --user-agent='Mozilla/5.0...'".

Q2: "External downloader aria2c not found"

Cause: The aria2c binary is not located in your system PATH variable.
Solution: On Windows, place aria2c.exe in the same folder as yt-dlp.exe or add it to system Environment Variables. On macOS, install via brew install aria2. On Ubuntu/Debian, install via sudo apt install aria2.

Q3: Does aria2 work for Live Streams (HLS / m3u8)?

Answer: aria2 is designed for static files with known Content-Length headers. For live streams or continuous HLS/DASH broadcasts, yt-dlp's native downloader or ffmpeg is automatically selected by default.