snagvid (vdl)

Download videos from YouTube, X/Twitter, Instagram, Facebook, or almost any website — straight from your terminal, no browser extensions, no sketchy websites.

Features

• 🧙 Interactive CLI Wizard: Simply type vdl to get guided prompts for URL, resolution, and output folder.
• 📊 Smart Resolution & Size Detection: Shows available resolutions with accurate combined video + audio download size estimates.
• 🎵 Audio Extraction: Easily extract high-quality audio tracks (e.g. MP3) directly.
• 🎨 Clean Live Progress: Real-time progress display with speed, ETA, and spinner animations powered by rich.
• 🌐 1800+ Supported Sites: Powered by yt-dlp for unmatched platform compatibility.
• ⚡ Scripting Ready: Pass URLs and flags directly (vdl "<url>" -q 720p) for automation.
• 🛡️ Long Title Protection: Automatic title truncation and ID tagging to prevent filesystem errors on long post captions.

Prerequisites

• Python: 3.9 or higher
• FFmpeg: Required for stream merging and audio extraction.
  • Linux: sudo apt install ffmpeg / sudo pacman -S ffmpeg
  • macOS: brew install ffmpeg

Installation

pip install snagvid
# or with pipx for isolated global installation:
pipx install snagvid

Local Development Install

git clone https://github.com/WaqasAhmad313/snagvid.git
cd snagvid
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Usage

Interactive Mode (Recommended)

Run vdl with no arguments to start the interactive wizard:

vdl

Direct / Scripted Usage

Pass arguments directly to bypass the interactive prompts:

# Direct download best quality
vdl "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

# Download audio-only (MP3)
vdl "https://www.youtube.com/watch?v=dQw4w9WgXcQ" --audio

# Download specific quality to custom directory
vdl "https://www.youtube.com/watch?v=dQw4w9WgXcQ" -q 720p -o ~/Videos

Configuration (~/.vdlrc)

You can save your default preferences in ~/.vdlrc (INI format):

[defaults]
output       = ~/Videos
quality      = 1080p
audio_format = mp3
retries      = 5

Supported Sites

vdl inherits complete extractor support from yt-dlp, covering 1800+ websites including YouTube, X/Twitter, Instagram, Facebook, TikTok, Twitch, Reddit, Vimeo, and SoundCloud.

For a full list of supported extractors, see the yt-dlp supported sites documentation.

Responsible Use

This tool is intended for downloading content you own, have explicit permission to use, or that is otherwise legally accessible to you — e.g. personal backups, offline access to your own posts, content licensed for reuse. Respect the terms of service of the platform you're downloading from and applicable copyright law. The maintainers are not responsible for misuse.

Contributing

Contributions are welcome!

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

Distributed under the MIT License. See LICENSE for details.