youtube-downloader

CLI utility for downloading a single YouTube video with explicit quality policy and machine-readable output.

Features

• Downloads one video from youtube.com or youtu.be URL.
• Supports strict exact-quality mode and best-effort fallback mode.
• Supports yt-dlp player client overrides and browser cookie import attempts.
• Provides stable machine-readable output with --output json.
• Supports doctor, describe, and fetch --dry-run for automation workflows.

Requirements

• Python 3.10+
• ffmpeg in PATH

Installation

python3 -m venv .venv
source .venv/bin/activate
pip install -e .\[dev\]

Configuration

Optional environment variables:

export YT_TARGET_QUALITY=720
export YT_QUALITY_POLICY=strict
export YT_COOKIES_FROM_BROWSER=chrome
export YT_PO_TOKEN_ANDROID=...
export YT_PO_TOKEN_IOS=...

Legacy YT_MIN_HEIGHT is still supported as a fallback for target quality.

Usage

Download a video:

youtube-downloader fetch "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

By default in text terminal mode, fetch shows an interactive quality selector (arrow keys + Enter).

Download to custom folder and JSON output:

youtube-downloader fetch "https://youtu.be/dQw4w9WgXcQ" --output-dir ./downloads --output json

Use strict target quality:

youtube-downloader fetch "https://www.youtube.com/watch?v=dQw4w9WgXcQ" --target-quality 1080 --quality-policy strict

Dry-run without writing files:

youtube-downloader fetch "https://www.youtube.com/watch?v=dQw4w9WgXcQ" --dry-run --output json

Disable interactive selector and use resolved/default quality directly:

youtube-downloader fetch "https://www.youtube.com/watch?v=dQw4w9WgXcQ" --no-interactive-quality

Inspect runtime environment:

youtube-downloader doctor

Describe command contract:

youtube-downloader describe fetch

Exit codes

• 0 success
• 2 invalid input or unsupported URL
• 3 missing runtime dependency
• 4 inaccessible video or extractor auth failure
• 5 no format matched requested quality constraints
• 6 restricted/protected content or unavailable auth context
• 7 yt-dlp/ffmpeg/runtime error

Notes

• This utility downloads one video from the exact URL passed to fetch.
• The default output directory is ./downloads.
• --name-template accepts {title}, {id}, {uploader}, {ext} placeholders or native yt-dlp template syntax.