pyutube 1.6.0

Awesome CLI to download YouTube videos (as video or audio)/shorts/playlists from the terminal

📹 Pyutube - The Simplest YouTube Downloader CLI

Enjoying my project? Please show your appreciation by starring it on GitHub! ⭐

[!IMPORTANT] ffmpeg must be available on your PATH for video merging and audio conversion.

[!NOTE] Have a feature request or bug report? tell me

Why Pyutube?

Pyutube is a small CLI wrapper around yt-dlp. It supports videos, shorts, audio-only downloads, and playlists with a simple prompt-driven flow. Video downloads are merged with the best available audio track, and audio downloads are transcoded to WAV by default with an optional MP3 conversion flag.

Because Pyutube delegates downloading to yt-dlp, it also inherits standard yt-dlp behavior such as:

• Resuming interrupted downloads when a partial file is still available
• Retrying transient network failures according to yt-dlp's defaults
• Selecting the best matching format from the available stream list
• Merging the chosen video stream with the best available audio stream

Pyutube does not expose every yt-dlp option directly, but the downloader underneath is still yt-dlp, so its normal download handling applies.

🛠️ Installation

Make sure Python is installed:

python --version

If you are developing locally, clone the repository and install the dependencies:

pip install -r requirements.txt -r requirements-dev.txt

To install the published package:

pip install pyutube

[!TIP] If the installation or update does not work, try running the command with the pip install pyutube --break-system-packages flag.

Then run pyutube --help to confirm the CLI is available.

📈 Upgrade

To upgrade the installed package:

pip install --upgrade pyutube

[!TIP] If the installation or update does not work, try running the command with the pip install --upgrade pyutube --break-system-packages flag.

🚀 Run It

Use either of these commands to view the CLI help:

pyutube --help
python -m pyutube --help

Download a video, short, or playlist with:

pyutube "YOUTUBE_LINK"
pyutube "YOUTUBE_LINK" "/path/to/save"

Common examples:

pyutube "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
pyutube "https://www.youtube.com/watch?v=dQw4w9WgXcQ" -a
pyutube "https://www.youtube.com/watch?v=dQw4w9WgXcQ" -a --mp3
pyutube "https://www.youtube.com/watch?v=dQw4w9WgXcQ" -f
pyutube "https://www.youtube.com/playlist?list=PLAYLIST_ID"

[!NOTE] The URL is required. The path is optional and defaults to the current working directory.

👨‍💻 Usage

Arguments

Arguments	Description
URL	The YouTube URL or video ID. This argument is required.
PATH	The path to save the video. Defaults to the current working directory. [Optional]

Options

Option	Description
-v or --version	Display the current version number.
-a or --audio	Download audio only as WAV, skipping prompts.
--mp3	Convert audio downloads to MP3.
-f or --footage	Download video only, skipping prompts.

🛠️ Code Quality

Run these commands to check code health locally:

python -m compileall pyutube
ruff check pyutube
mypy pyutube

The repo also includes a short checklist in QUALITY.md.

🕵️‍♂️ Examples

More examples are in EXAMPLES.md.

🥰 Contributing

Pull requests are welcome. For larger changes, open an issue first and follow the contributing guidelines.

📎 License

This project is licensed under the MIT License.

📸 Screenshots

Download a video to a specific location

Choose what type to download

Choose a resolution when downloading video

Select playlist items to download

Need help? Run pyutube --help

⏳ Todo List

• Notification System
• Auto Update package if new version available
• Support Optional Numbering for Downloaded Playlist Videos
• Improve code health
• Support downloading sounds (WAV by default, MP3 optional)
• Support Subtitles Download
• Support setting for downloading folder
• Download Thumbnails with Videos and Audio