Skip to main content
yt-dlp can be used as a Python library to integrate video downloading capabilities into your applications. This allows you to programmatically download videos, extract metadata, and process media content.

​
Installation

Install yt-dlp via pip: 
pip install yt-dlp
For development or specific features, you may need additional dependencies: 
pip install yt-dlp[default]  # Recommended dependencies

​
Basic Usage

The main entry point for using yt-dlp as a library is the YoutubeDL class: 
import yt_dlp

# Basic download
ydl_opts = {}
with yt_dlp.YoutubeDL(ydl_opts) as ydl:
    ydl.download(['https://www.youtube.com/watch?v=dQw4w9WgXcQ'])

​
Extract Information Without Downloading

You can extract video metadata without downloading the actual video file: 
import yt_dlp

ydl_opts = {
    'skip_download': True,
}

with yt_dlp.YoutubeDL(ydl_opts) as ydl:
    info = ydl.extract_info('https://www.youtube.com/watch?v=dQw4w9WgXcQ', download=False)
    print(f"Title: {info['title']}")
    print(f"Duration: {info['duration']} seconds")
    print(f"Uploader: {info['uploader']}")

​
Common Options

The YoutubeDL class accepts a dictionary of options. Here are some commonly used options:
​
format
string
Video format code (e.g., ‘best’, ‘bestvideo+bestaudio’, ‘720p’)
​
outtmpl
string | dict
Output filename template. Can be a string or dictionary with keys like ‘default’
​
quiet
boolean
default:"false"
Do not print messages to stdout
​
no_warnings
boolean
default:"false"
Do not print out anything for warnings
​
ignoreerrors
boolean | string
default:"false"
Continue on download errors. Can be ‘only_download’ to ignore only download errors
​
extract_flat
boolean | string
default:"false"
Do not resolve URLs or process playlist items. Can be ‘in_playlist’, ‘discard’, or ‘discard_in_playlist’

​
Simple Example

import yt_dlp

def download_video(url, output_path='downloads'):
    ydl_opts = {
        'format': 'bestvideo+bestaudio/best',
        'outtmpl': f'{output_path}/%(title)s.%(ext)s',
        'quiet': False,
    }
    
    with yt_dlp.YoutubeDL(ydl_opts) as ydl:
        ydl.download([url])

if __name__ == '__main__':
    download_video('https://www.youtube.com/watch?v=dQw4w9WgXcQ')

​
Information Dictionary

When you extract information, yt-dlp returns a dictionary containing video metadata. Common fields include:
  • id: Video identifier
  • title: Video title
  • description: Video description
  • uploader: Video uploader name
  • duration: Video duration in seconds
  • view_count: Number of views
  • like_count: Number of likes
  • formats: List of available formats
  • thumbnails: List of thumbnail dictionaries
  • subtitles: Dictionary of available subtitles

​
Error Handling

import yt_dlp
from yt_dlp.utils import DownloadError, ExtractorError

try:
    with yt_dlp.YoutubeDL({'quiet': True}) as ydl:
        ydl.download(['https://example.com/video'])
except DownloadError as e:
    print(f"Download failed: {e}")
except ExtractorError as e:
    print(f"Extraction failed: {e}")

​
Next Steps

YoutubeDL Class

Deep dive into the main YoutubeDL class and its methods

Extractors

Learn about the extractor system and how to work with different sites

Post-Processors

Process downloaded media with post-processors

Examples

Browse practical code examples for common use cases