📹 Pyutube - The Simplest YouTube Downloader CLI

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

Note

Pyutube is built on top of pytubefix. If downloads stop working, update it first:

pip install --upgrade pytubefix

Note

Have a feature request or bug report? tell me

Why Pyutube?

Pyutube is a small CLI wrapper around pytubefix. It supports videos, shorts, audio-only downloads, and playlists with a simple prompt-driven flow. Audio downloads are saved as WAV by default, with an optional MP3 conversion flag.

🛠️ 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.

🧪 Test And Quality

Run these commands to check code health locally:

python -m compileall pyutube
pytest pyutube/tests -q
ruff check pyutube
mypy pyutube
coverage run -m pytest pyutube/tests -q
coverage report

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