A lightweight YouTube video downloader with a desktop app, system tray, web UI, and CLI.
License: AGPL-3.0 Python 3.8+ CI
- Desktop App — Double-click to launch. No terminal needed.
- System Tray — Quick access tray icon for managing the app.
- Web UI — Full browser interface with real-time download queue and progress.
- CLI —
python cli.py <URL>for quick terminal downloads. - Best Quality — Automatically merges best video + audio into MP4 (requires ffmpeg).
- Dark / Light Mode — Follows your OS theme.
- Download Queue — Start multiple downloads simultaneously; track progress per item.
- 16 Languages — Auto-detects OS locale (en, ko, ja, zh-TW, zh-CN, de, es, fr, pt, vi, ms, id, th, ru, it, ar).
- Cross-Platform — Windows, macOS, Linux.
- Python 3.8+
- ffmpeg (required for high-quality video/audio merging)
- Windows:
winget install ffmpegor https://ffmpeg.org/download.html - macOS:
brew install ffmpeg - Linux:
sudo apt install ffmpeg
- Windows:
git clone https://github.com/5throck/QuickDL.git
cd QuickDL
python install.pyinstall.py automatically:
- Verifies Python version (3.8+)
- Creates a virtual environment (
.venv/) - Installs all dependencies from
requirements.txt - Installs
ffmpegvia package manager (winget, brew, apt) if missing - Sets required environment variables (
PYTHONIOENCODING=utf-8)
Windows — double-click ytdl.bat
macOS / Linux:
chmod +x ytdl.sh ./ytdl.sh
Or run directly:
python desktop.py
The app opens a window with the full web UI and adds a tray icon.
Closing the window will completely exit the application. You can also quit via the tray icon.
python app.py
# Open http://localhost:5000Paste a YouTube URL, click Download, and watch the real-time progress queue.
When complete, a download link appears — click to save the file.
# Basic download (saved to ./downloads/) python cli.py <YouTube URL> # Custom output folder python cli.py <YouTube URL> --output /path/to/folder # Force a specific language QUICKDL_LANG=ko python cli.py <URL> # macOS/Linux set QUICKDL_LANG=ko && python cli.py <URL> # Windows
QuickDL/
├── app.py # Flask server — routes, job queue, file serving
├── download_service.py # yt-dlp wrapper (get_video_info, download_video)
├── desktop.py # Desktop entry point (pywebview + pystray)
├── cli.py # CLI entry point (argparse)
├── install.py # Cross-platform installer
├── i18n.py # i18n: init(), t(), get_all(), format_duration()
├── requirements.txt # Python dependencies
├── ytdl.bat # Windows one-click launcher
├── ytdl.sh # macOS/Linux one-click launcher
├── locales/ # 16 flat JSON translation files (en.json is baseline)
├── templates/index.html # Web UI (Jinja2)
├── static/
│ ├── css/styles.css # UI styles (dark + light, responsive)
│ └── js/script.js # Frontend JS (fetch, queue, polling)
├── tests/
│ ├── test_app.py # Flask API tests (9 tests — unittest)
│ ├── test_i18n.py # i18n tests (14 tests — pytest)
│ └── test_env.py # Dependency check
├── scripts/
│ ├── audit.sh / audit.ps1 # Quality gate
│ └── dev-sync.sh / dev-sync.ps1 # PR pipeline
└── docs/context.md # Project context for AI tools
pytest tests/ -v # All 23 tests bash scripts/audit.sh # Quality gate (CHANGELOG, i18n parity, broken links)
This project is licensed under the GNU Affero General Public License v3.0.