Embedding yt-dlp

Learn how to embed yt-dlp in Python applications

yt-dlp can be embedded in Python applications for programmatic access to its powerful downloading and extraction capabilities.

Command-Line Integration

yt-dlp makes the best effort to be a good command-line program and should be callable from any programming language.

Your program should avoid parsing the normal stdout since they may change in future versions. Instead, use options such as -J, --print, --progress-template, --exec etc. to create console output that you can reliably reproduce and parse.

Python Integration

From a Python program, you can embed yt-dlp in a more powerful fashion.

Basic Usage

from yt_dlp import YoutubeDL

URLS = ['https://www.youtube.com/watch?v=BaW_jenozKc']
with YoutubeDL() as ydl:
    ydl.download(URLS)

Configuration Options

For a list of available options:

• Check yt_dlp/YoutubeDL.py
• Use help(yt_dlp.YoutubeDL) in a Python shell
• Use devscripts/cli_to_api.py to translate CLI switches to YoutubeDL params

If you are porting code from youtube-dl to yt-dlp, note that we do not guarantee the return value of YoutubeDL.extract_info to be JSON serializable, or even be a dictionary. It will be dictionary-like, but if you want to ensure it is a serializable dictionary, pass it through YoutubeDL.sanitize_info as shown in the examples below.

Common Examples

Extracting Information

Extract video metadata without downloading:

import json
import yt_dlp

URL = 'https://www.youtube.com/watch?v=BaW_jenozKc'

# ℹ️ See help(yt_dlp.YoutubeDL) for a list of available options and public functions
ydl_opts = {}
with yt_dlp.YoutubeDL(ydl_opts) as ydl:
    info = ydl.extract_info(URL, download=False)

    # ℹ️ ydl.sanitize_info makes the info json-serializable
    print(json.dumps(ydl.sanitize_info(info)))

Download Using an Info JSON

Download videos from a previously saved info.json file:

import yt_dlp

INFO_FILE = 'path/to/video.info.json'

with yt_dlp.YoutubeDL() as ydl:
    error_code = ydl.download_with_info_file(INFO_FILE)

print('Some videos failed to download' if error_code
      else 'All videos successfully downloaded')

Extract Audio

Download and convert videos to audio-only files:

import yt_dlp

URLS = ['https://www.youtube.com/watch?v=BaW_jenozKc']

ydl_opts = {
    'format': 'm4a/bestaudio/best',
    # ℹ️ See help(yt_dlp.postprocessor) for a list of available Postprocessors and their arguments
    'postprocessors': [{  # Extract audio using ffmpeg
        'key': 'FFmpegExtractAudio',
        'preferredcodec': 'm4a',
    }]
}

with yt_dlp.YoutubeDL(ydl_opts) as ydl:
    error_code = ydl.download(URLS)

Filter Videos

Download only videos that match specific criteria:

import yt_dlp

URLS = ['https://www.youtube.com/watch?v=BaW_jenozKc']

def longer_than_a_minute(info, *, incomplete):
    """Download only videos longer than a minute (or with unknown duration)"""
    duration = info.get('duration')
    if duration and duration < 60:
        return 'The video is too short'

ydl_opts = {
    'match_filter': longer_than_a_minute,
}

with yt_dlp.YoutubeDL(ydl_opts) as ydl:
    error_code = ydl.download(URLS)

Adding Logger and Progress Hook

Custom logging and progress tracking:

import yt_dlp

URLS = ['https://www.youtube.com/watch?v=BaW_jenozKc']

class MyLogger:
    def debug(self, msg):
        # For compatibility with youtube-dl, both debug and info are passed into debug
        # You can distinguish them by the prefix '[debug] '
        if msg.startswith('[debug] '):
            pass
        else:
            self.info(msg)

    def info(self, msg):
        pass

    def warning(self, msg):
        pass

    def error(self, msg):
        print(msg)


# ℹ️ See "progress_hooks" in help(yt_dlp.YoutubeDL)
def my_hook(d):
    if d['status'] == 'finished':
        print('Done downloading, now post-processing ...')


ydl_opts = {
    'logger': MyLogger(),
    'progress_hooks': [my_hook],
}

with yt_dlp.YoutubeDL(ydl_opts) as ydl:
    ydl.download(URLS)

Add a Custom PostProcessor

Create custom postprocessing logic:

import yt_dlp

URLS = ['https://www.youtube.com/watch?v=BaW_jenozKc']

# ℹ️ See help(yt_dlp.postprocessor.PostProcessor)
class MyCustomPP(yt_dlp.postprocessor.PostProcessor):
    def run(self, info):
        self.to_screen('Doing stuff')
        return [], info


with yt_dlp.YoutubeDL() as ydl:
    # ℹ️ "when" can take any value in yt_dlp.utils.POSTPROCESS_WHEN
    ydl.add_post_processor(MyCustomPP(), when='pre_process')
    ydl.download(URLS)

Use a Custom Format Selector

Implement custom format selection logic:

import yt_dlp

URLS = ['https://www.youtube.com/watch?v=BaW_jenozKc']

def format_selector(ctx):
    """ Select the best video and the best audio that won't result in an mkv.
    NOTE: This is just an example and does not handle all cases """

    # formats are already sorted worst to best
    formats = ctx.get('formats')[::-1]

    # acodec='none' means there is no audio
    best_video = next(f for f in formats
                      if f['vcodec'] != 'none' and f['acodec'] == 'none')

    # find compatible audio extension
    audio_ext = {'mp4': 'm4a', 'webm': 'webm'}[best_video['ext']]
    # vcodec='none' means there is no video
    best_audio = next(f for f in formats if (
        f['acodec'] != 'none' and f['vcodec'] == 'none' and f['ext'] == audio_ext))

    # These are the minimum required fields for a merged format
    yield {
        'format_id': f'{best_video["format_id"]}+{best_audio["format_id"]}',
        'ext': best_video['ext'],
        'requested_formats': [best_video, best_audio],
        # Must be + separated list of protocols
        'protocol': f'{best_video["protocol"]}+{best_audio["protocol"]}'
    }


ydl_opts = {
    'format': format_selector,
}

with yt_dlp.YoutubeDL(ydl_opts) as ydl:
    ydl.download(URLS)

API Reference

YoutubeDL Class

The main class for interacting with yt-dlp programmatically.

Key Methods

• extract_info(url, download=True) - Extract information from a URL
• download(url_list) - Download videos from a list of URLs
• download_with_info_file(info_file) - Download from an info.json file
• sanitize_info(info_dict) - Make info dict JSON-serializable
• add_post_processor(pp, when='post_process') - Add a custom postprocessor

Common Options

ydl_opts = {
    'format': 'bestvideo+bestaudio/best',  # Format selection
    'outtmpl': '%(title)s.%(ext)s',        # Output template
    'quiet': True,                          # Suppress console output
    'no_warnings': True,                    # Suppress warnings
    'extract_flat': False,                  # Extract full info
    'ignoreerrors': False,                  # Stop on errors
}

Best Practices

Use Context Managers

Always use with YoutubeDL() as ydl: to ensure proper resource cleanup.

Sanitize Info

Use sanitize_info() when you need JSON-serializable output.

Handle Errors

Wrap extraction/download calls in try-except blocks to handle errors gracefully.

Check Return Codes

Check error codes from download() methods to detect failures.

Migration from youtube-dl

The return value of YoutubeDL.extract_info is not guaranteed to be JSON serializable or a standard dictionary in yt-dlp. Always use sanitize_info() if you need serializable output.

Related Resources

• YoutubeDL Source Code
• CLI to API Converter
• PostProcessor Documentation