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

> Learn to enable verbose debugging and traffic logging in youtube dl. Use the -v flag for detailed output and --print-traffic for raw network logs to troubleshoot issues effectively.

- Repository: [youtube-dl/youtube-dl](https://github.com/ytdl-org/youtube-dl)
- Tags: how-to-guide
- Published: 2026-02-25

---

**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`](https://github.com/ytdl-org/youtube-dl/blob/main/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`](https://github.com/ytdl-org/youtube-dl/blob/main/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`](https://github.com/ytdl-org/youtube-dl/blob/main/youtube_dl/YoutubeDL.py), [`youtube_dl/extractor/common.py`](https://github.com/ytdl-org/youtube-dl/blob/main/youtube_dl/extractor/common.py), and [`youtube_dl/postprocessor/ffmpeg.py`](https://github.com/ytdl-org/youtube-dl/blob/main/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`](https://github.com/ytdl-org/youtube-dl/blob/main/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`](https://github.com/ytdl-org/youtube-dl/blob/main/youtube_dl/YoutubeDL.py), the code initializes network handlers with:

```python
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`](https://github.com/ytdl-org/youtube-dl/blob/main/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:**

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

```

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

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

```

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

```bash
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`](https://github.com/ytdl-org/youtube-dl/blob/main/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`](https://github.com/ytdl-org/youtube-dl/blob/main/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`](https://github.com/ytdl-org/youtube-dl/blob/main/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`](https://github.com/ytdl-org/youtube-dl/blob/main/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`](https://github.com/ytdl-org/youtube-dl/blob/main/youtube_dl/extractor/common.py)** – Checks the verbose flag to emit additional extractor-specific debugging information.

- **[`youtube_dl/postprocessor/ffmpeg.py`](https://github.com/ytdl-org/youtube-dl/blob/main/youtube_dl/postprocessor/ffmpeg.py)** – Respects the verbose setting when constructing and executing ffmpeg commands.

- **[`youtube_dl/downloader/external.py`](https://github.com/ytdl-org/youtube-dl/blob/main/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`](https://github.com/ytdl-org/youtube-dl/blob/main/youtube_dl/options.py) and propagate through [`YoutubeDL.py`](https://github.com/ytdl-org/youtube-dl/blob/main/YoutubeDL.py) and [`networking.py`](https://github.com/ytdl-org/youtube-dl/blob/main/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`](https://github.com/ytdl-org/youtube-dl/blob/main/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`](https://github.com/ytdl-org/youtube-dl/blob/main/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`](https://github.com/ytdl-org/youtube-dl/blob/main/youtube_dl/options.py) and consumed by the networking stack in [`youtube_dl/YoutubeDL.py`](https://github.com/ytdl-org/youtube-dl/blob/main/youtube_dl/YoutubeDL.py) and [`youtube_dl/networking.py`](https://github.com/ytdl-org/youtube-dl/blob/main/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.