0
# yt-dlp
1

2
A feature-rich command-line audio/video downloader forked from youtube-dl that supports downloading from thousands of video hosting sites including YouTube, Vimeo, Twitch, and many others. It provides extensive format selection capabilities, audio extraction, subtitle downloading, post-processing features, and advanced configuration options for customizing downloads.
3

4
## Package Information
5

6
- **Package Name**: yt-dlp
7
- **Package Type**: PyPI
8
- **Language**: Python
9
- **Installation**: `pip install yt-dlp`
10
- **Requirements**: Python 3.9+
11

12
## Core Imports
13

14
```python
15
import yt_dlp
16
```
17

18
For main functionality:
19

20
```python
21
from yt_dlp import YoutubeDL
22
```
23

24
For extractor system:
25

26
```python
27
from yt_dlp import gen_extractors, list_extractors
28
from yt_dlp.extractor import gen_extractor_classes, list_extractor_classes, get_info_extractor
29
```
30

31
For utilities:
32

33
```python
34
from yt_dlp.utils import sanitize_filename, parse_duration, parse_bytes, unified_timestamp
35
from yt_dlp import Config, DateRange, FormatSorter, PlaylistEntries
36
```
37

38
For configuration and options:
39

40
```python
41
from yt_dlp import parse_options, main
42
from yt_dlp.options import parseOpts
43
```
44

45
## Basic Usage
46

47
```python
48
import yt_dlp
49

50
# Basic download using the main API class
51
with yt_dlp.YoutubeDL() as ydl:
52
    ydl.download(['https://www.youtube.com/watch?v=example'])
53

54
# Download with custom options
55
ydl_opts = {
56
    'format': 'best[height<=720]',
57
    'outtmpl': '%(title)s.%(ext)s',
58
    'writesubtitles': True,
59
    'writeautomaticsub': True,
60
}
61

62
with yt_dlp.YoutubeDL(ydl_opts) as ydl:
63
    ydl.download(['https://www.youtube.com/watch?v=example'])
64

65
# Extract information without downloading
66
ydl_opts = {'skip_download': True}
67
with yt_dlp.YoutubeDL(ydl_opts) as ydl:
68
    info = ydl.extract_info('https://www.youtube.com/watch?v=example')
69
    print(f"Title: {info['title']}")
70
    print(f"Duration: {info['duration']} seconds")
71
```
72

73
## Architecture
74

75
yt-dlp follows a modular architecture designed for extensibility and robustness:
76

77
- **YoutubeDL Class**: Central coordinator managing downloads, extractors, post-processors, and configuration
78
- **Extractor System**: 1000+ site-specific extractors for different video platforms, each handling URL patterns, metadata extraction, and format discovery
79
- **Post-Processor Pipeline**: Configurable chain of processors for audio extraction, video conversion, metadata embedding, and file manipulation
80
- **Networking Layer**: Multi-backend HTTP handling with browser impersonation, proxy support, and cookie management
81
- **Utility System**: Comprehensive utilities for filename sanitization, format parsing, template processing, and error handling
82

83
This design enables yt-dlp to handle the complexity of extracting media from diverse platforms while providing a simple Python API for integration into other applications.
84

85
## Capabilities
86

87
### Core Download API
88

89
The primary YoutubeDL class providing download management, information extraction, and configuration. This is the main interface for programmatic use of yt-dlp functionality.
90

91
```python { .api }
92
class YoutubeDL:
93
    def __init__(self, params=None, auto_init=True): ...
94
    def download(self, url_list): ...
95
    def extract_info(self, url, download=True, ie_key=None, extra_info=None, process=True, force_generic_extractor=False): ...
96
    def process_ie_result(self, ie_result, download=True, extra_info=None): ...
97
```
98

99
[Core Download API](./core-download.md)
100

101
### Extractor System
102

103
Discovery and management of site-specific extractors that handle URL pattern matching, metadata extraction, and format enumeration for supported video platforms.
104

105
```python { .api }
106
def gen_extractors(): ...
107
def list_extractors(age_limit=None): ...
108
def gen_extractor_classes(): ...
109
def list_extractor_classes(age_limit=None): ...
110
def get_info_extractor(ie_name): ...
111
```
112

113
[Extractor System](./extractor-system.md)
114

115
### CLI and Configuration
116

117
Command-line interface functions and option parsing for configuring yt-dlp behavior programmatically.
118

119
```python { .api }
120
def main(argv=None): ...
121
def parse_options(argv=None): ...
122
def parseOpts(overrideArguments=None, ignore_config_files='if_override'): ...
123
```
124

125
[Configuration Options](./configuration.md)
126

127
### Utility Functions
128

129
Comprehensive utility functions for file handling, data parsing, URL processing, format conversion, and template processing commonly needed when working with media downloads.
130

131
```python { .api }
132
def sanitize_filename(s, restricted=False, is_id=False): ...
133
def parse_duration(s): ...
134
def parse_bytes(s): ...
135
def unified_timestamp(date_str, day_first=True): ...
136
class Config: ...
137
class DateRange: ...
138
class FormatSorter: ...
139
class PlaylistEntries: ...
140
```
141

142
[Utility Functions](./utilities.md)
143

144
### Post-Processing
145

146
Configurable pipeline of processors for audio extraction, video conversion, subtitle handling, metadata embedding, and other file transformations applied after download.
147

148
```python { .api }
149
class FFmpegExtractAudioPP: ...
150
class FFmpegMergerPP: ...
151
class FFmpegPostProcessor: ...
152
class FFmpegSubtitlesConvertorPP: ...
153
class FFmpegThumbnailsConvertorPP: ...
154
class FFmpegVideoConvertorPP: ...
155
class FFmpegVideoRemuxerPP: ...
156
class MetadataFromFieldPP: ...
157
class MetadataParserPP: ...
158
```
159

160
[Post-Processing](./post-processing.md)
161

162
### Configuration Options
163

164
Comprehensive configuration system with 100+ parameters controlling download behavior, format selection, output templates, networking, and post-processing options.
165

166
```python { .api }
167
def parse_options(argv=None): ...
168
def parseOpts(overrideArguments=None, ignore_config_files='if_override'): ...
169
```
170

171
[Configuration Options](./configuration.md)
172

173
### Exception Handling
174

175
Rich exception hierarchy providing detailed error information for different failure modes including network errors, extraction failures, and post-processing issues.
176

177
```python { .api }
178
class YoutubeDLError(Exception): ...
179
class ExtractorError(YoutubeDLError): ...
180
class DownloadError(YoutubeDLError): ...
181
class DownloadCancelled(YoutubeDLError): ...
182
class SameFileError(YoutubeDLError): ...
183
class PostProcessingError(YoutubeDLError): ...
184
```
185

186
[Exception Handling](./exceptions.md)
187

188
## Types
189

190
```python { .api }
191
# Core configuration dictionary for YoutubeDL
192
YDLOptions = dict[str, Any]
193

194
# Information dictionary returned by extractors
195
InfoDict = dict[str, Any]
196

197
# Format information dictionary
198
FormatDict = dict[str, Any]
199

200
# Progress hook function signature
201
ProgressHook = Callable[[dict[str, Any]], None]
202

203
# Post-processor hook function signature
204
PostProcessorHook = Callable[[dict[str, Any]], None]
205
```