General Options

Core yt-dlp options for help, updates, error handling, and configuration

-h, --help · flag

Print help text and exit

--version · flag

Print program version and exit

-U, --update · flag

Update this program to the latest version

--no-update · flag · default: "true"

Do not check for updates

--update-to · string

Upgrade/downgrade to a specific version. Format: [CHANNEL]@[TAG]

CHANNEL can be a repository as well. CHANNEL and TAG default to “stable” and “latest” respectively if omitted.

Supported channels: stable, nightly, master

Example:

yt-dlp --update-to nightly
yt-dlp --update-to stable@2023.07.06

Error Handling

-i, --ignore-errors · flag

Ignore download and postprocessing errors. The download will be considered successful even if the postprocessing fails

--no-abort-on-error · flag · default: "true"

Continue with next video on download errors; e.g. to skip unavailable videos in a playlist

--abort-on-error · flag

Abort downloading of further videos if an error occurs

Alias: --no-ignore-errors

Extractors

--list-extractors · flag

List all supported extractors and exit

--extractor-descriptions · flag

Output descriptions of all supported extractors and exit

--use-extractors · string

Extractor names to use separated by commas. You can also use regexes, “all”, “default” and “end” (end URL matching)

Prefix the name with a ”-” to exclude it. Use --list-extractors for a list of extractor names.

Alias: --ies

Example:

yt-dlp --ies "holodex.*,end,youtube"
yt-dlp --ies default,-generic

--default-search · string

Use this prefix for unqualified URLs

Values:

• auto - Let yt-dlp guess
• auto_warning - Emit a warning when guessing
• error - Throw an error
• fixup_error (default) - Repair broken URLs, but emit an error if not possible

Example:

yt-dlp --default-search "gvsearch2:python"  # Downloads 2 videos from Google Videos

Configuration

--ignore-config · flag

Don’t load any more configuration files except those given to --config-locations

For backward compatibility, if this option is found inside the system configuration file, the user configuration is not loaded.

Alias: --no-config

--no-config-locations · flag · default: "true"

Do not load any custom configuration files. When given inside a configuration file, ignore all previous --config-locations defined in the current file

--config-locations · string

Location of the main configuration file; either the path to the config or its containing directory (”-” for stdin)

Can be used multiple times and inside other configuration files

Plugins

--plugin-dirs · string

Path to an additional directory to search for plugins. This option can be used multiple times to add multiple directories.

Use “default” to search the default plugin directories

--no-plugin-dirs · flag

Clear plugin directories to search, including defaults and those provided by previous --plugin-dirs

JavaScript Runtime

--js-runtimes · string

Additional JavaScript runtime to enable, with an optional location for the runtime

Format: RUNTIME[:PATH] where PATH is either the path to the binary or its containing directory

This option can be used multiple times to enable multiple runtimes.

Supported runtimes (in priority order): deno, node, quickjs, bun

Only “deno” is enabled by default. The highest priority runtime that is both enabled and available will be used.

--no-js-runtimes · flag

Clear JavaScript runtimes to enable, including defaults and those provided by previous --js-runtimes

Remote Components

--remote-components · string

Remote components to allow yt-dlp to fetch when required

This option is currently not needed if you are using an official executable or have the requisite version of the yt-dlp-ejs package installed.

Supported values:

• ejs:npm - External JavaScript components from npm
• ejs:github - External JavaScript components from yt-dlp-ejs GitHub

By default, no remote components are allowed

--no-remote-components · flag

Disallow fetching of all remote components, including any previously allowed by --remote-components or defaults

Playlist Options

--flat-playlist · flag

Do not extract a playlist’s URL result entries; some entry metadata may be missing and downloading may be bypassed

--no-flat-playlist · flag · default: "true"

Fully extract the videos of a playlist

Livestream Options

--live-from-start · flag

Download livestreams from the start

Currently experimental and only supported for YouTube, Twitch, and TVer

--no-live-from-start · flag · default: "true"

Download livestreams from the current time

--wait-for-video · string

Wait for scheduled streams to become available

Pass the minimum number of seconds (or range) to wait between retries

Format: MIN[-MAX]

--no-wait-for-video · flag · default: "true"

Do not wait for scheduled streams

--mark-watched · flag

Mark videos watched (even with --simulate)

--no-mark-watched · flag · default: "true"

Do not mark videos watched

Output Formatting

--color · string

Whether to emit color codes in output, optionally prefixed by the STREAM (stdout or stderr) to apply the setting to

Format: [STREAM:]POLICY

Values:

• always
• auto (default)
• never
• no_color - Use non color terminal sequences
• auto-tty - Decide based on terminal support only
• no_color-tty

Can be used multiple times

Compatibility

--compat-options · string

Options that can help keep compatibility with youtube-dl or youtube-dlc configurations by reverting some of the changes made in yt-dlp

See “Differences in default behavior” for details

Aliases

--alias · string

Create aliases for an option string

Unless an alias starts with a dash ”-”, it is prefixed with ”—”. Arguments are parsed according to the Python string formatting mini-language.

This option can be used multiple times. Each alias may be triggered a maximum of 100 times as a safety measure.

Example:

yt-dlp --alias get-audio,-X "-S aext:{0},abr -x --audio-format {0}"
# Creates --get-audio and -X that takes an argument and expands the options

-t, --preset-alias · string

Applies a predefined set of options

Available presets: mp3, aac, mp4, mkv, sleep

See the “Preset Aliases” section for more info. This option can be used multiple times.

Example:

yt-dlp -t mp3 URL

Verbosity and Simulation

-q, --quiet · flag

Activate quiet mode

If used with --verbose, print the log to stderr

Example:

yt-dlp -q URL

--no-quiet · flag · default: "true"

Deactivate quiet mode

--no-warnings · flag

Ignore warnings

-s, --simulate · flag

Do not download the video and do not write anything to disk

Example:

yt-dlp -s URL  # Just simulate, don't download

--no-simulate · flag · default: "true"

Download the video even if printing/listing options are used

--ignore-no-formats-error · flag

Ignore “No video formats” error

Useful for extracting metadata even if the videos are not actually available for download (experimental)

--no-ignore-no-formats-error · flag · default: "true"

Throw error when no downloadable video formats are found

--skip-download · flag

Do not download the video but write all related files

Alias: --no-download

-O, --print · string

Field name or output template to print to screen, optionally prefixed with when to print it, separated by a ”:”

Format: [WHEN:]TEMPLATE

Supported values of “WHEN” are the same as that of --use-postprocessor (default: video). Implies --quiet. Implies --simulate unless --no-simulate or later stages of WHEN are used.

This option can be used multiple times.

Example:

yt-dlp -O "%(title)s - %(uploader)s" URL
yt-dlp -O "after_move:filepath" URL

--print-to-file · string

Append given template to the file

Format: [WHEN:]TEMPLATE FILE

The values of WHEN and TEMPLATE are the same as that of --print. FILE uses the same syntax as the output template.

This option can be used multiple times.

Example:

yt-dlp --print-to-file "%(title)s" titles.txt URL

-j, --dump-json · flag

Quiet, but print JSON information for each video

Simulate unless --no-simulate is used. See “OUTPUT TEMPLATE” for a description of available keys.

Example:

yt-dlp -j URL

-J, --dump-single-json · flag

Quiet, but print JSON information for each URL or infojson passed

Simulate unless --no-simulate is used. If the URL refers to a playlist, the whole playlist information is dumped in a single line.

--force-write-archive · flag

Force download archive entries to be written as far as no errors occur, even if -s or another simulation option is used

Alias: --force-download-archive

--newline · flag

Output progress bar as new lines

--no-progress · flag

Do not print progress bar

--progress · flag

Show progress bar, even if in quiet mode

--console-title · flag

Display progress in console titlebar

--progress-template · string

Template for progress outputs, optionally prefixed by the TYPES

Format: [TYPES:]TEMPLATE

Example:

yt-dlp --progress-template "download:%(progress.eta)s"

-v, --verbose · flag

Print various debugging information

Example:

yt-dlp -v URL

--dump-pages · flag

Print downloaded pages encoded using base64 to debug problems (very verbose)

--write-pages · flag

Write downloaded intermediary pages to files in the current directory to debug problems

--print-traffic · flag

Display sent and read HTTP traffic

Workarounds

--encoding · string

Force the specified encoding (experimental)

--legacy-server-connect · flag

Explicitly allow HTTPS connection to servers that do not support RFC 5746 secure renegotiation

--no-check-certificates · flag

Suppress HTTPS certificate validation

Use with caution - this disables security checks

--prefer-insecure · flag

Use an unencrypted connection to retrieve information about the video

Currently supported only for YouTube

--add-headers · string

Specify a custom HTTP header and its value, separated by a colon ”:”

You can use this option multiple times.

Example:

yt-dlp --add-headers "Referer: https://example.com" URL

--bidi-workaround · flag

Work around terminals that lack bidirectional text support

Requires bidiv or fribidi executable in PATH

--sleep-requests · number

Number of seconds to sleep between requests during data extraction

Example:

yt-dlp --sleep-requests 1 URL

--sleep-interval · number

Number of seconds to sleep before each download

This is the minimum time to sleep when used along with --max-sleep-interval

Alias: --min-sleep-interval

Example:

yt-dlp --sleep-interval 5 URL

--max-sleep-interval · number

Maximum number of seconds to sleep

Can only be used along with --min-sleep-interval

Example:

yt-dlp --sleep-interval 3 --max-sleep-interval 10 URL

--sleep-subtitles · number

Number of seconds to sleep before each subtitle download