Configuration¶

VDL stores user configuration in a TOML file.

Config File Location¶

~/.config/vdl/config.toml

View and Modify Config¶

CLI¶

# Show entire config
vdl config show

# Get a single key
vdl config get output_dir

# Set a key
vdl config set max_concurrent_downloads 5

Edit Directly¶

nano ~/.config/vdl/config.toml

Programmatically¶

from vdl import VDLClient, VDLConfig
from pathlib import Path

# Create a custom config
config = VDLConfig(
    output_dir=Path("~/Videos"),
    default_quality="1080p",
    max_concurrent_downloads=2
)
client = VDLClient(config=config)

Config Fields¶

Key	Type	Default	Description
`output_dir`	path	`~/Downloads/VDL`	Default download destination
`default_quality`	string	`best`	Default quality preference
`audio_only`	bool	`false`	Extract audio only (no video)
`max_concurrent_downloads`	int	`3`	Max parallel downloads per batch
`embed_metadata`	bool	`true`	Embed metadata in video file
`embed_thumbnail`	bool	`true`	Embed thumbnail in video (if possible)
`write_thumbnail`	bool	`false`	Save thumbnail as sidecar `.jpg`
`write_subtitles`	bool	`false`	Save subtitle files
`subtitle_langs`	string	`en`	Comma-separated language codes
`max_playlist_items`	int or null	null	Limit playlist expansion (no limit if null)
`expand_nested_playlists`	bool	`false`	Recursively expand playlists in link files
`concurrent_fragments`	int or null	null	Parallel fragment downloads per item
`write_info_json`	bool	`false`	Save yt-dlp `.info.json` sidecar
`extractor_args`	dict or null	null	Per-extractor yt-dlp overrides
`ytdlp_channel`	string or null	null	Preferred yt-dlp channel (informational)
`js_runtime_path`	string or null	null	Path to custom JS runtime (deno/node)
`site_rules_path`	path or null	null	Path to custom `websites.yaml` for discovery

Sample Config¶

# Output directory for downloads
output_dir = "~/Downloads/VDL"

# Quality preference: best, medium, low, 2160p, 1440p, 1080p, 720p, 480p, audio
default_quality = "best"

# Download audio only (no video track)
audio_only = false

# Concurrent downloads (affects playlist and batch performance)
max_concurrent_downloads = 3

# Embedding options (applied post-download if possible)
embed_metadata = true
embed_thumbnail = true

# Write sidecar files (in addition to embedding)
write_thumbnail = false
write_subtitles = false
subtitle_langs = "en"

# Playlist behavior
max_playlist_items = null         # null = no limit
expand_nested_playlists = false

# Fragment download concurrency (advanced)
concurrent_fragments = null       # null = auto-detect

# yt-dlp integration
write_info_json = false           # Save .info.json alongside video
ytdlp_channel = null              # Prefer stable, nightly, etc.
js_runtime_path = null            # Explicit path to node/deno

# Discovery (page crawling)
site_rules_path = null            # Use default or custom rules

# Per-extractor options (pass through to yt-dlp)
[extractor_args]
# youtube = { player_client = ["web", "tv"] }

Default Paths¶

Purpose	Default	Env Var
Config	`~/.config/vdl/`	n/a
State	`~/.local/state/vdl/`	n/a
Cache	`~/.cache/vdl/`	n/a
Logs	`~/.local/state/vdl/logs/`	(under state)
Downloads	`~/Downloads/VDL`	(configured path)

First-Run Initialization¶

The first time you run VDL interactively, it automatically: 1. Creates ~/.config/vdl/ directory 2. Writes a default config.toml with all fields 3. Downloads bundled websites.yaml for discovery 4. Initializes the SQLite state database

If any file already exists, it is not overwritten.

Reset Configuration¶

To reset to defaults:

# Backup the old config
cp ~/.config/vdl/config.toml ~/.config/vdl/config.toml.bak

# Delete and let VDL recreate it
rm ~/.config/vdl/config.toml
vdl  # Recreates default config

Common Customizations¶

Change Download Folder¶

vdl config set output_dir ~/Videos

Increase Download Concurrency¶

vdl config set max_concurrent_downloads 5

Always Download Audio-Only¶

vdl config set audio_only true
vdl config set default_quality audio

Enable Subtitles by Default¶

vdl config set write_subtitles true
vdl config set subtitle_langs "en,es,fr"

Limit Playlist Size¶

vdl config set max_playlist_items 20

Custom Site Rules¶

For page crawling, use your own site rules:

vdl config set site_rules_path ~/.config/vdl/my-rules.yaml

The rules file format is a YAML list of site rules. See the bundled websites.yaml in the VDL installation for the schema.

Environment Variable Overrides¶

Direct env var overrides for config values or config/state/cache path roots are not supported. Use vdl config set or edit the TOML file directly.

Config Validation¶

VDL validates the config file on load:

vdl config show
# If invalid, prints error and uses safe defaults

To check for issues:

vdl doctor

Any config errors are reported in the vdl doctor output.