0
# Pytube
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: pytube
7
- **Language**: Python
8
- **Installation**: `pip install pytube`
9
- **Version**: 15.0.0
10
- **License**: The Unlicense (public domain)
11

12
## Core Imports
13

14
```python
15
from pytube import YouTube, Stream, Caption, Playlist, Channel, Search
16
```
17

18
For individual video operations:
19
```python
20
from pytube import YouTube
21
```
22

23
For working with collections:
24
```python
25
from pytube import Playlist, Channel, Search
26
```
27

28
## Basic Usage
29

30
```python
31
from pytube import YouTube
32

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

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

39
# Download the video
40
stream.download()
41

42
# Access video metadata
43
print(f"Title: {yt.title}")
44
print(f"Author: {yt.author}")
45
print(f"Views: {yt.views}")
46
print(f"Length: {yt.length} seconds")
47

48
# Download audio only
49
audio_stream = yt.streams.filter(only_audio=True).first()
50
audio_stream.download(filename_prefix="audio_")
51
```
52

53
## Architecture
54

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

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

64
## Capabilities
65

66
### Video Downloads and Metadata
67

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

70
```python { .api }
71
class YouTube:
72
    def __init__(
73
        self,
74
        url: str,
75
        on_progress_callback: Optional[Callable[[Any, bytes, int], None]] = None,
76
        on_complete_callback: Optional[Callable[[Any, Optional[str]], None]] = None,
77
        proxies: Dict[str, str] = None,
78
        use_oauth: bool = False,
79
        allow_oauth_cache: bool = True
80
    ): ...
81
    
82
    @property
83
    def streams(self) -> StreamQuery: ...
84
    
85
    @property  
86
    def title(self) -> str: ...
87
    
88
    @property
89
    def author(self) -> str: ...
90
    
91
    @property
92
    def views(self) -> int: ...
93
```
94

95
[Video Downloads](./video-downloads.md)
96

97
### Stream Management and Filtering
98

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

101
```python { .api }
102
class StreamQuery:
103
    def filter(
104
        self,
105
        fps=None,
106
        res=None, 
107
        resolution=None,
108
        mime_type=None,
109
        type=None,
110
        subtype=None,
111
        file_extension=None,
112
        abr=None,
113
        bitrate=None,
114
        video_codec=None,
115
        audio_codec=None,
116
        only_audio=None,
117
        only_video=None,
118
        progressive=None,
119
        adaptive=None,
120
        is_dash=None,
121
        custom_filter_functions=None
122
    ) -> StreamQuery: ...
123
    
124
    def get_highest_resolution(self) -> Optional[Stream]: ...
125
    def get_lowest_resolution(self) -> Optional[Stream]: ...
126
    def get_audio_only(self, subtype: str = "mp4") -> Optional[Stream]: ...
127

128
class Stream:
129
    def download(
130
        self,
131
        output_path: Optional[str] = None,
132
        filename: Optional[str] = None,
133
        filename_prefix: Optional[str] = None,
134
        skip_existing: bool = True,
135
        timeout: Optional[int] = None,
136
        max_retries: Optional[int] = 0
137
    ) -> str: ...
138
```
139

140
[Stream Management](./stream-management.md)
141

142
### Caption and Subtitle Support
143

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

146
```python { .api }
147
class Caption:
148
    @property
149
    def code(self) -> str: ...
150
    
151
    @property
152
    def name(self) -> str: ...
153
    
154
    def generate_srt_captions(self) -> str: ...
155
    
156
    def download(
157
        self,
158
        title: str,
159
        srt: bool = True,
160
        output_path: Optional[str] = None,
161
        filename_prefix: Optional[str] = None
162
    ) -> str: ...
163

164
class CaptionQuery:
165
    def __getitem__(self, lang_code: str) -> Caption: ...
166
```
167

168
[Captions](./captions.md)
169

170
### Collection Operations
171

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

174
```python { .api }
175
class Playlist:
176
    def __init__(self, url: str, proxies: Optional[Dict[str, str]] = None): ...
177
    
178
    @property
179
    def videos(self) -> Iterable[YouTube]: ...
180
    
181
    @property
182
    def video_urls(self) -> DeferredGeneratorList: ...
183
    
184
    @property
185
    def title(self) -> Optional[str]: ...
186

187
class Channel(Playlist):
188
    @property
189
    def channel_name(self) -> str: ...
190
    
191
    @property
192
    def channel_id(self) -> str: ...
193

194
class Search:
195
    def __init__(self, query: str): ...
196
    
197
    @property
198
    def results(self) -> list: ...
199
    
200
    def get_next_results(self) -> None: ...
201
```
202

203
[Collections](./collections.md)
204

205
### Exception Handling
206

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

209
```python { .api }
210
class PytubeError(Exception): ...
211

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

215
class AgeRestrictedError(VideoUnavailable): ...
216
class LiveStreamError(VideoUnavailable): ...
217
class VideoPrivate(VideoUnavailable): ...
218
```
219

220
[Exceptions](./exceptions.md)
221

222
## Types
223

224
```python { .api }
225
from typing import Any, Callable, Dict, List, Optional, Union, Iterable
226
from datetime import datetime, date
227
from io import BinaryIO
228

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

233
# Stream filtering types  
234
FilterValue = Union[str, int, bool, None]
235
CustomFilterFunction = Callable[[Stream], bool]
236
```