How to Enable Verbose Debugging and Traffic Logging in youtube-dl

Use the -v or --verbose flag to enable detailed debugging output, and add --print-traffic to log raw HTTP request and response headers during network operations.

When troubleshooting failed downloads or analyzing how ytdl-org/youtube-dl interacts with video hosting platforms, you need deep visibility into the extraction and networking stack. The tool provides built-in command-line flags that activate comprehensive debugging and HTTP traffic logging without requiring any source code modifications.

Understanding the Core Debugging Flags

youtube-dl uses an optparse-based command-line parser defined in youtube_dl/options.py to convert user flags into entries of the internal opts namespace.

The Verbose Flag (-v and --verbose)

The --verbose flag (short form -v) activates miscellaneous debugging information throughout the extraction and download process. According to the source code in youtube_dl/options.py, this flag sets the verbose key in the options namespace to True.

When enabled, youtube-dl checks self.params.get('verbose') in multiple locations including youtube_dl/YoutubeDL.py, youtube_dl/extractor/common.py, and youtube_dl/postprocessor/ffmpeg.py. These checks trigger additional console output showing extractor logic, ffmpeg command construction, and detailed error messages.

The Traffic Logging Flag (--print-traffic)

The --print-traffic flag (also accessible as --dump-headers in some contexts) enables raw HTTP request and response logging. In youtube_dl/options.py, this maps to the debug_printtraffic namespace key.

This flag directly controls the debuglevel parameter passed to urllib handlers. In youtube_dl/YoutubeDL.py, the code initializes network handlers with:

debuglevel = 1 if self.params.get('debug_printtraffic') else 0
https_handler = make_HTTPS_handler(self.params, debuglevel=debuglevel)
ydlh = YoutubeDLHandler(self.params, debuglevel=debuglevel)

The make_HTTPS_handler function in youtube_dl/networking.py forwards this debug level to urllib.request.HTTPSHandler. When debuglevel is non-zero, the underlying http.client.HTTPConnection prints each request line and response header to stderr, which youtube-dl displays in your terminal.

Practical Usage Examples

Combine these flags to diagnose different types of issues:

Basic verbose debugging:

youtube-dl --verbose https://www.youtube.com/watch?v=example

Log only HTTP traffic (useful for analyzing redirects or authentication):

youtube-dl --print-traffic https://www.youtube.com/watch?v=example

Maximum debugging output (verbose + traffic + external tool verbosity):

youtube-dl --verbose --print-traffic https://www.youtube.com/watch?v=example

When you use --verbose, youtube-dl also propagates the flag to external downloaders. For example, in youtube_dl/downloader/external.py, the code automatically adds --verbose to the command line when invoking rtmpdump or other external tools.

Key Source Files Involved

The debugging functionality spans several core modules:

• youtube_dl/options.py – Defines the --verbose and --print-traffic command-line arguments and their mapping to the internal options namespace.

• youtube_dl/YoutubeDL.py – Reads self.params['verbose'] and self.params['debug_printtraffic'] to configure the HTTP handler debug levels and trigger verbose output throughout the extraction process.

• youtube_dl/networking.py – Implements make_HTTPS_handler() which forwards the debuglevel parameter to urllib's HTTPSHandler, enabling the raw HTTP traffic output.

• youtube_dl/extractor/common.py – Checks the verbose flag to emit additional extractor-specific debugging information.

• youtube_dl/postprocessor/ffmpeg.py – Respects the verbose setting when constructing and executing ffmpeg commands.

• youtube_dl/downloader/external.py – Propagates the verbose flag to external downloader processes like rtmpdump.

Summary

• Use -v or --verbose to enable detailed debugging output across extractors, post-processors, and external downloaders.
• Use --print-traffic to log raw HTTP request and response headers, revealing redirect chains, cookie handling, and CDN interactions.
• Combine both flags for comprehensive troubleshooting of download failures.
• These options require no code modifications; they are fully integrated into youtube_dl/options.py and propagate through YoutubeDL.py and networking.py.

Frequently Asked Questions

What is the difference between --verbose and --print-traffic in youtube-dl?

The --verbose flag activates high-level debugging information throughout the application, showing extractor logic, post-processor commands, and internal state changes. The --print-traffic flag specifically enables low-level network debugging by printing raw HTTP request and response headers to stderr. Use --verbose for general troubleshooting and --print-traffic when diagnosing network-specific issues like redirects or authentication failures.

Where does youtube-dl write verbose debug output?

By default, youtube-dl writes all verbose debugging and traffic logging output to stderr (standard error), not stdout. This ensures that diagnostic information does not interfere with piped output or file redirections of the actual video data. You can redirect this output to a file using shell redirection, for example: youtube-dl --verbose URL 2> debug.log.

Can I enable verbose debugging for external downloaders like ffmpeg or rtmpdump?

Yes. When you pass the --verbose flag to youtube-dl, it automatically propagates this setting to external downloaders. In youtube_dl/downloader/external.py, the code checks the verbose parameter and appends --verbose to the command-line arguments of tools like rtmpdump. For ffmpeg specifically, the post-processor in youtube_dl/postprocessor/ffmpeg.py also checks the verbose flag to determine whether to display the full command output or suppress it.

Do I need to modify the source code to enable HTTP traffic logging?

No. HTTP traffic logging is fully integrated into the command-line interface and requires no source code modifications. The --print-traffic flag is defined in youtube_dl/options.py and consumed by the networking stack in youtube_dl/YoutubeDL.py and youtube_dl/networking.py. These components automatically configure the underlying urllib handlers with the appropriate debug level, causing http.client to emit raw HTTP headers to stderr.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}