6.4 KiB
YouTube Downloader
Powered by yt-dlp • Cross-platform • Python 3.8+
Version 1.0
Overview
This package provides two Python scripts that together let you download YouTube videos and audio to your computer with a simple interactive menu. No programming knowledge is required to use them.
| File | Purpose |
|---|---|
yt_downloader.py |
Main script — interactive downloader with quality selection |
install_dependencies.py |
One-time setup — installs yt-dlp and ffmpeg automatically |
README.md |
This document |
System Requirements
| Requirement | Details |
|---|---|
| Python | Version 3.8 or newer (python --version to check) |
| pip | Included with Python 3.4+; upgraded automatically by installer |
| yt-dlp | Installed automatically by install_dependencies.py |
| ffmpeg | Installed automatically by install_dependencies.py (optional but strongly recommended) |
| Internet | Required for downloading videos |
| Disk space | Varies by video length and quality — allow at least 500 MB free |
Note: ffmpeg is optional but required for 1080p/4K quality and MP3 audio conversion. Without it the downloader falls back to pre-muxed formats (typically 720p max).
Quick Start
Step 1 — Run the installer (once only)
Open a terminal or command prompt in the folder containing the scripts, then run:
python install_dependencies.py
The installer will automatically detect your operating system and install everything needed. You should see green checkmarks confirming success.
Step 2 — Download a video
python yt_downloader.py
Follow the on-screen prompts:
- Paste the YouTube URL and press Enter
- Choose an action: download video, download audio, or list formats
- Select a quality (if downloading video)
- Choose a save folder (default is
./downloadsin the same directory)
Installer — install_dependencies.py
Run this script once before using the downloader. It is safe to run again at any time; it will upgrade existing installations.
What it installs
- pip — upgraded to the latest version to avoid dependency resolver issues
- yt-dlp — the core download engine (kept up to date)
- ffmpeg — the media processing library used for merging video/audio streams and converting to MP3
Platform support
| Platform | ffmpeg install method |
|---|---|
| Windows | winget → Chocolatey → Scoop (uses whichever is found first) |
| macOS | Homebrew (installs Homebrew automatically if not present) |
| Linux — Debian / Ubuntu | apt-get |
| Linux — Fedora / RHEL | dnf + RPM Fusion repository |
| Linux — Arch Linux | pacman |
After the installer runs
A verification step checks both tools and reports their detected versions. If ffmpeg shows a warning instead of a checkmark, try opening a new terminal window and running the installer again — PATH changes sometimes require a terminal restart.
Downloader — yt_downloader.py
Startup check
When launched the script immediately checks for ffmpeg and shows its status:
- ✅ Green checkmark — full quality available including 1080p, 4K, and MP3 audio
- ⚠️ Warning — ffmpeg not found; quality limited to ~720p and audio saves as
.m4a
Menu options
| Option | Description |
|---|---|
| 1 — Download video | Downloads as MP4. Prompts for quality selection (see below). |
| 2 — Download audio only | Extracts audio. Saves as MP3 (with ffmpeg) or .m4a (without). |
| 3 — List available formats | Prints every available format ID, extension, resolution, and FPS for the given URL. Useful for troubleshooting. |
Quality options
| Quality | Behaviour |
|---|---|
| best (default) | Highest available quality for the video |
| 1080p | Up to 1920 × 1080 — requires ffmpeg |
| 720p | Up to 1280 × 720 |
| 480p | Up to 854 × 480 |
| 360p | Up to 640 × 360 — smallest file size |
Output folder
By default files are saved to a downloads/ subfolder next to the script. You can type any absolute or relative path at the prompt, for example:
C:\Users\Alice\Videos (Windows)
/home/alice/Videos (macOS / Linux)
./my-downloads (relative path, any OS)
How quality selection works internally
YouTube streams high-quality video and audio as separate files. ffmpeg is used to merge them after download. When ffmpeg is not available the script automatically switches to pre-muxed single-file formats to avoid errors — this is why quality is capped at ~720p without ffmpeg.
Troubleshooting
| Error / Symptom | Solution |
|---|---|
ffmpeg is not installed. Aborting due to --abort-on-error |
Run install_dependencies.py, then open a new terminal and try again. |
python: command not found |
Try python3 instead. On Windows, ensure Python is added to PATH during installation. |
pip is not recognised |
Run: python -m ensurepip --upgrade |
| Download stops or gives HTTP 403 | Update yt-dlp: pip install --upgrade yt-dlp (YouTube changes its API regularly) |
| Age-restricted or private video fails | These videos require authentication. yt-dlp supports cookie-based login — see the yt-dlp documentation. |
| 1080p not available after installing ffmpeg | Restart your terminal so the updated PATH takes effect, then try again. |
| Very slow download speed | Normal for large files. Progress is shown during download. Check your internet connection. |
Keeping Things Up to Date
YouTube frequently changes its internal API. If downloads suddenly stop working, update yt-dlp:
pip install --upgrade yt-dlp
You can also re-run the installer at any time — it upgrades all components safely.
Legal Notice
This tool is intended for personal use only. Downloading copyrighted content without the rights holder's permission may violate YouTube's Terms of Service and applicable copyright law. Only download content you have the right to download — such as your own uploads, Creative Commons-licensed videos, or content explicitly made available for offline use.
Quick Reference Card
| Task | Command |
|---|---|
| First-time setup | python install_dependencies.py |
| Download a video | python yt_downloader.py |
| Update yt-dlp only | pip install --upgrade yt-dlp |
| Check ffmpeg version | ffmpeg -version |
| Check yt-dlp version | yt-dlp --version |