pytube

pytube is a Python library and CLI for downloading YouTube videos, playlists, and caption tracks without pulling in heavyweight dependencies. It exposes a YouTube object that parses a video’s page to discover available streams, then lets you filter and download by resolution, file type, or adaptive/progressive format.

Beyond single-video downloads, it ships Playlist and Channel classes for bulk operations, caption extraction, and metadata access, plus a pytube console script for command-line use. Because it works by reverse-engineering YouTube’s internal player response and cipher logic rather than calling an official API, it requires periodic maintenance to track upstream changes to YouTube’s page structure.

What You Get

• A YouTube class that parses a video page into a queryable StreamQuery of available video/audio streams
• Playlist and Channel classes for iterating and bulk-downloading every video in a playlist or channel
• Caption track extraction and download via the captions module
• A pytube console-script CLI for quick downloads without writing Python
• A cipher-decryption module (cipher.py) that decodes YouTube’s signature obfuscation so protected streams remain downloadable

Common Use Cases

• Archiving a personal YouTube video or playlist for offline viewing
• Building a small internal tool that extracts specific audio/video streams from a list of YouTube URLs
• Downloading caption tracks in bulk for transcript-based research or dataset building
• Scripting channel-wide backups by iterating a Channel object’s video list

Under The Hood

Architecture - pytube/__main__.py (479 lines) defines the core YouTube class, which fetches a video’s watch page and player-response JSON, then hands off to extract.py for parsing stream metadata and cipher.py (697 lines) for reversing YouTube’s signature-cipher obfuscation on protected streams. streams.py (436 lines) wraps the parsed stream list in a StreamQuery/Stream API for filtering and downloading, while contrib/ holds the higher-level Playlist and Channel classes that iterate many videos through the same core pipeline. Because there’s no official download API, this whole chain is a reverse-engineered scrape of YouTube’s internal page structure, which is why the project needs regular updates when YouTube changes its player internals.

Tech Stack - Pure Python 3.7+ with zero required third-party dependencies (only stdlib urllib/re/json), which keeps installation trivial but pushes all HTTP, regex-parsing, and JS-cipher-emulation work into the library itself rather than delegating to requests or similar. Packaging is classic setup.py/Pipfile rather than a modern pyproject.toml, and the console-script entry point is registered as pytube = pytube.cli:main.

Code Quality - The tests/ directory mirrors the source layout closely (test_cipher.py, test_extract.py, test_streams.py, test_query.py, etc., plus a contrib/ subfolder and mocks/ for fixture data), giving solid coverage of the parsing and cipher logic that’s most exposed to upstream breakage. A dedicated exceptions.py defines library-specific exceptions (e.g. for age-restricted or unavailable videos) instead of relying on raw exceptions, and monostate.py centralizes shared session state cleanly.

API Design - The primary flow — YouTube(url).streams.filter(...).first().download() — is fluent and requires very little boilerplate for the common case, and Playlist/Channel reuse the same .streams pattern for bulk operations. The main developer-experience risk isn’t the API shape but its stability against an external, unversioned dependency (YouTube’s own page structure), which the project mitigates somewhat via the cipher/extract split but can’t fully insulate against.