or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

captions.mdcollections.mdexceptions.mdindex.mdstream-management.mdvideo-downloads.md
tile.json

tessl/pypi-pytube

Python library for downloading YouTube videos with comprehensive stream management and metadata extraction capabilities.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/pytube@15.0.x

To install, run

npx @tessl/cli install tessl/pypi-pytube@15.0.0

index.mddocs/

Pytube

A lightweight, dependency-free Python library for downloading YouTube videos. Pytube provides comprehensive video download capabilities including support for both progressive and DASH streams, complete playlist downloads, and caption track extraction with .srt format output.

Package Information

  • Package Name: pytube
  • Language: Python
  • Installation: pip install pytube
  • Version: 15.0.0
  • License: The Unlicense (public domain)

Core Imports

from pytube import YouTube, Stream, Caption, Playlist, Channel, Search

For individual video operations:

from pytube import YouTube

For working with collections:

from pytube import Playlist, Channel, Search

Basic Usage

from pytube import YouTube

# Download a single video
yt = YouTube('https://www.youtube.com/watch?v=9bZkp7q19f0')

# Get the highest resolution progressive stream
stream = yt.streams.get_highest_resolution()

# Download the video
stream.download()

# Access video metadata
print(f"Title: {yt.title}")
print(f"Author: {yt.author}")
print(f"Views: {yt.views}")
print(f"Length: {yt.length} seconds")

# Download audio only
audio_stream = yt.streams.filter(only_audio=True).first()
audio_stream.download(filename_prefix="audio_")

Architecture

Pytube is organized around core classes that handle different aspects of YouTube content:

  • YouTube: Primary interface for single video operations, metadata extraction, and stream access
  • Stream: Represents individual downloadable streams with specific quality/format combinations
  • StreamQuery: Filtering and selection interface for stream collections
  • Caption/CaptionQuery: Caption track management and .srt conversion
  • Playlist/Channel/Search: Collection-based operations for multiple videos
  • Exception hierarchy: Comprehensive error handling for various failure scenarios

Capabilities

Video Downloads and Metadata

Core functionality for downloading individual YouTube videos and extracting comprehensive metadata including title, description, view counts, thumbnails, and publication information.

class YouTube:
    def __init__(
        self,
        url: str,
        on_progress_callback: Optional[Callable[[Any, bytes, int], None]] = None,
        on_complete_callback: Optional[Callable[[Any, Optional[str]], None]] = None,
        proxies: Dict[str, str] = None,
        use_oauth: bool = False,
        allow_oauth_cache: bool = True
    ): ...
    
    @property
    def streams(self) -> StreamQuery: ...
    
    @property  
    def title(self) -> str: ...
    
    @property
    def author(self) -> str: ...
    
    @property
    def views(self) -> int: ...

Video Downloads

Stream Management and Filtering

Advanced stream selection and filtering capabilities for choosing specific video qualities, formats, and codecs from available options.

class StreamQuery:
    def filter(
        self,
        fps=None,
        res=None, 
        resolution=None,
        mime_type=None,
        type=None,
        subtype=None,
        file_extension=None,
        abr=None,
        bitrate=None,
        video_codec=None,
        audio_codec=None,
        only_audio=None,
        only_video=None,
        progressive=None,
        adaptive=None,
        is_dash=None,
        custom_filter_functions=None
    ) -> StreamQuery: ...
    
    def get_highest_resolution(self) -> Optional[Stream]: ...
    def get_lowest_resolution(self) -> Optional[Stream]: ...
    def get_audio_only(self, subtype: str = "mp4") -> Optional[Stream]: ...

class Stream:
    def download(
        self,
        output_path: Optional[str] = None,
        filename: Optional[str] = None,
        filename_prefix: Optional[str] = None,
        skip_existing: bool = True,
        timeout: Optional[int] = None,
        max_retries: Optional[int] = 0
    ) -> str: ...

Stream Management

Caption and Subtitle Support

Caption track extraction and conversion to .srt format with support for multiple languages and automatic subtitle generation.

class Caption:
    @property
    def code(self) -> str: ...
    
    @property
    def name(self) -> str: ...
    
    def generate_srt_captions(self) -> str: ...
    
    def download(
        self,
        title: str,
        srt: bool = True,
        output_path: Optional[str] = None,
        filename_prefix: Optional[str] = None
    ) -> str: ...

class CaptionQuery:
    def __getitem__(self, lang_code: str) -> Caption: ...

Captions

Collection Operations

Playlist, channel, and search functionality for working with multiple videos, including bulk downloads and metadata extraction.

class Playlist:
    def __init__(self, url: str, proxies: Optional[Dict[str, str]] = None): ...
    
    @property
    def videos(self) -> Iterable[YouTube]: ...
    
    @property
    def video_urls(self) -> DeferredGeneratorList: ...
    
    @property
    def title(self) -> Optional[str]: ...

class Channel(Playlist):
    @property
    def channel_name(self) -> str: ...
    
    @property
    def channel_id(self) -> str: ...

class Search:
    def __init__(self, query: str): ...
    
    @property
    def results(self) -> list: ...
    
    def get_next_results(self) -> None: ...

Collections

Exception Handling

Comprehensive exception hierarchy for handling various error conditions including video availability, network issues, and extraction failures.

class PytubeError(Exception): ...

class VideoUnavailable(PytubeError):
    def __init__(self, video_id: str): ...

class AgeRestrictedError(VideoUnavailable): ...
class LiveStreamError(VideoUnavailable): ...
class VideoPrivate(VideoUnavailable): ...

Exceptions

Types

from typing import Any, Callable, Dict, List, Optional, Union, Iterable
from datetime import datetime, date
from io import BinaryIO

# Callback function types
ProgressCallback = Callable[[Any, bytes, int], None]
CompleteCallback = Callable[[Any, Optional[str]], None]

# Stream filtering types  
FilterValue = Union[str, int, bool, None]
CustomFilterFunction = Callable[[Stream], bool]