A fast, user-friendly desktop application to download YouTube videos and playlists with a clean PyQt6 interface.
✨ Easy to Use
- Paste YouTube URLs (videos, playlists, channels, handles)
- Clean, intuitive interface
- Real-time progress tracking
📦 Batch Downloading
- Queue multiple URLs at once
- Download entire playlists
- Saved queue persists between sessions
⚙️ Customizable
- Choose video quality (best, 1080p, 720p, 480p, audio-only)
- Select output format (MP4, MKV, WebM)
- Set default download folder
🛡️ Reliable
- Automatic retry on failures (up to 3 times)
- Thread-safe multi-threaded downloads
- Detailed error messages
- View application logs for debugging
⏸️ Control
- Pause/stop downloads at any time
- Cancel individual items in queue
- Clear completed items
Visit the Official Download Page to download the latest version for your operating system.
The page automatically detects your OS and offers the right download button. Or manually download:
- macOS:
VidGrab.dmg(drag to Applications) - Windows:
VidGrab.exe(double-click to run) - Linux:
VidGrab(make executable and run)
No installation needed, just download and run!
If you prefer to run from source or want to modify the code:
- Clone the repository:
git clone https://github.com/yourusername/vidgrab.git
cd vidgrab- Create a virtual environment:
python3 -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate- Install dependencies:
pip install -r requirements.txt- Run the app:
python -m mainWant to build an executable yourself? See BUILDING.md for detailed instructions on building for macOS, Windows, and Linux.
- Paste a URL in the input field (e.g.,
https://www.youtube.com/watch?v=...) - Click "Add to Queue" - the app fetches the video title automatically
- Repeat to add multiple videos/playlists
Click Settings to customize:
- Download Folder: Where videos are saved (default: ~/Downloads)
- Video Quality: best, 1080p, 720p, 480p, or audio-only
- Format: MP4, MKV, or WebM
- Choose a download folder (if not using default)
- Click "Start Downloads" to begin processing the queue
- Watch progress in real-time on each item and overall
- Click "Stop" to pause the queue and cancel current download
- Resume by clicking "Start Downloads" again
Click View Logs to open the application log file. Useful for:
- Troubleshooting failed downloads
- Checking detailed error messages
- Understanding what happened during a download session
✅ Single videos
https://www.youtube.com/watch?v=dQw4w9WgXcQ
https://youtu.be/dQw4w9WgXcQ
✅ Playlists
https://www.youtube.com/playlist?list=PLxxx
✅ Channels
https://www.youtube.com/channel/UCxxx
✅ Handles (custom URLs)
https://www.youtube.com/@username
- Downloads: Saved to your configured download folder (default: ~/Downloads)
- Settings:
~/.vidgrab/config.json - Queue:
~/.vidgrab/queue.json(auto-saved) - Logs:
~/.vidgrab/logs/app.log
| Shortcut | Action |
|---|---|
| Ctrl+A | Add to Queue |
| Ctrl+S | Start Downloads |
| Ctrl+Q | Quit application |
- Check the error message in the dialog
- Click View Logs for more details
- Verify the URL is still valid (video might be deleted/private)
- The app will automatically retry up to 3 times
- This is normal for large files
- The app is downloading in the background
- If frozen for >2 minutes, try clicking Stop then Start Downloads again
- Ensure you clicked Save in the Settings dialog
- Check
~/.vidgrab/config.jsonfile exists - Restart the app and try again
- Logs are created after the first download
- Click View Logs only after attempting a download
- Check
~/.vidgrab/logs/directory
- Quality Selection: Lower quality downloads faster (720p instead of best)
- Audio-Only: Much faster if you just want the audio
- Batch Downloads: Queue multiple items to download continuously
- Age-restricted videos may not download without authentication
- Private videos cannot be downloaded (as expected)
- Very large playlists (1000+ videos) may take time to process
- Network-dependent: Slow internet = slower downloads
- No data collection - all processing is local
- No account tracking - works completely offline after yt-dlp update
- No advertisements - open-source and free
Found a bug? Help us improve:
- Check the logs - Click "View Logs" to see error details
- Collect info - Note the exact URL, settings, and error message
- Report - Open an issue on GitHub with:
- What you were trying to do
- The error message
- Your OS and Python version
- Log file contents (optional but helpful)
We welcome contributions! Whether bug fixes, features, or documentation:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit changes (
git commit -m 'Add amazing feature') - Push to branch (
git push origin feature/amazing-feature) - Open a Pull Request
Complete documentation for users and developers:
- Installation Guide - Detailed macOS setup and Gatekeeper workaround
- CHANGELOG - Version history, features, and release notes
- License - MIT License terms
- Building - Build executables for macOS, Windows, Linux
- Deployment - Release and CI/CD process
- Contributing - Contribution guidelines and code style
MIT License - Copyright © 2026 Elabo Evans
See LICENSE file for full details.
See CHANGELOG.md for detailed roadmap:
- Basic download functionality
- Queue management
- Settings customization
- Error handling & retry
- Queue persistence
- Keyboard shortcuts (v1.1)
- Right-click context menu (v1.1)
- Completion notifications (v1.1)
- Open folder button (v1.1)
- Download history (v1.2)
- Batch URL input (v1.2)
- Parallel downloads (v2.0 - architectural change)
- Video conversion tools (v2.0)
Need help? Check these resources:
- Troubleshooting: See "Troubleshooting" section above
- Installation Issues: See MACOS_INSTALLATION.md
- Build Issues: See BUILDING.md
- Feature Requests: See CONTRIBUTING.md
- Bug Reports: See CONTRIBUTING.md
- Logs: Click "View Logs" in app to debug issues
Version: 1.0.0 | Last Updated: February 2026
Made with ❤️ for the YouTube download community