# How to Use the youtube-dl Match-Filter System for Precise Video Selection

> Master the youtube-dl match-filter system to precisely select videos based on metadata like duration, views, or uploader. Download exactly what you need with custom expressions.

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

---

**The youtube-dl match-filter system allows you to filter individual videos after extraction by evaluating metadata conditions such as duration, view count, or uploader name against user-defined expressions.**

The match-filter system in youtube-dl provides granular control over which videos are downloaded by evaluating each video's `info_dict` against custom criteria. Implemented across three core modules in the ytdl-org/youtube-dl repository, this system parses filter expressions at startup and applies them during the download pipeline to skip unwanted content without external scripting.

## How the Match-Filter System Works in youtube-dl

The match-filter system operates through a three-stage pipeline that bridges command-line input to runtime video evaluation.

### Command-Line Option Registration

The `--match-filter` argument is defined in [`youtube_dl/options.py`](https://github.com/ytdl-org/youtube-dl/blob/main/youtube_dl/options.py) (lines 308-321), where it accepts a raw filter string and stores it in the parameters dictionary. This registration captures the user's filtering intent before any video extraction begins.

### Filter Parsing and Compilation

In [`youtube_dl/utils.py`](https://github.com/ytdl-org/youtube-dl/blob/main/youtube_dl/utils.py), the `match_filter_func` (lines 4436-4450) transforms the raw string into an executable closure. This function leverages `match_str` and `_match_one` to parse the expression into atomic operations:

- **AND semantics** are enforced by splitting on the `&` operator.
- **Presence checks** validate that a key exists (`description`) or is absent (`!description`).
- **Numeric comparisons** handle operators `>`, `<`, `>=`, `<=`, `!=`, and `=`.
- **String literals** support single or double quotes, with an optional `?` suffix to treat missing values as acceptable.

### Runtime Application

During execution, [`youtube_dl/YoutubeDL.py`](https://github.com/ytdl-org/youtube-dl/blob/main/youtube_dl/YoutubeDL.py) (lines 826-831) invokes the stored filter function for each video's `info_dict`. A return value of `None` permits the download to proceed, while any non-`None` string (the rejection reason) skips the video and logs the explanation.

## Match-Filter Syntax and Operators

The match-filter system supports a specific grammar for constructing filter expressions:

- **Key presence** — `description` requires the field to exist.
- **Key absence** — `!description` requires the field to be missing.
- **Numeric comparison** — `view_count > 1000`, `filesize <= 5MiB`, `duration >= 60`.
- **String equality** — `uploader = "Mike Smith"`, `title != "Demo Video"`.
- **Unknown value tolerance** — append `?` to the operator (`dislike_count <? 50`) to pass when the field is missing.
- **Multiple conditions** — join with `&` for logical AND. No OR operator is provided; chain separate `--match-filter` invocations if needed.

## Practical Examples: Using Match-Filters in youtube-dl

### Filter by Duration and Uploader

To download only videos longer than 30 seconds from a specific creator:

```bash
youtube-dl --match-filter "duration > 30 & uploader = \"Mike Smith\"" \
           "https://www.youtube.com/playlist?list=PL12345"

```

### Handle Missing Metadata Gracefully

To require a description field while ignoring missing dislike counts:

```bash
youtube-dl --match-filter "description & dislike_count <? 50" \
           https://www.youtube.com/watch?v=abc123

```

The `?` suffix after `<` ensures the filter passes if `dislike_count` is not provided by the extractor.

### Programmatic Filter Usage in Python

For dynamic filter construction, use the Python API directly:

```python
from youtube_dl import YoutubeDL
from youtube_dl.utils import match_filter_func

# Build a filter for videos larger than 5MiB with at least 1,000 views

my_filter = match_filter_func('filesize > 5MiB & view_count >= 1000')

ydl_opts = {'match_filter': my_filter}
with YoutubeDL(ydl_opts) as ydl:
    ydl.download(['https://www.youtube.com/watch?v=xyz789'])

```

This approach allows runtime generation of filter strings based on external configuration.

## Summary

- The match-filter system evaluates video metadata after extraction but before downloading, living in [`youtube_dl/options.py`](https://github.com/ytdl-org/youtube-dl/blob/main/youtube_dl/options.py), [`youtube_dl/utils.py`](https://github.com/ytdl-org/youtube-dl/blob/main/youtube_dl/utils.py), and [`youtube_dl/YoutubeDL.py`](https://github.com/ytdl-org/youtube-dl/blob/main/youtube_dl/YoutubeDL.py).
- Filters support numeric comparisons, string matching, presence checks, and logical AND operations via the `&` operator.
- The `?` suffix on operators allows filters to pass when metadata fields are missing, preventing extraction failures.
- Both command-line `--match-filter` arguments and programmatic `match_filter_func` calls enable flexible video selection without external scripting.

## Frequently Asked Questions

### What is the match-filter system in youtube-dl?

The match-filter system is a post-extraction filtering mechanism that evaluates each video's `info_dict` against user-defined criteria before downloading. According to the ytdl-org/youtube-dl source code, it is implemented across [`youtube_dl/options.py`](https://github.com/ytdl-org/youtube-dl/blob/main/youtube_dl/options.py), [`youtube_dl/utils.py`](https://github.com/ytdl-org/youtube-dl/blob/main/youtube_dl/utils.py), and [`youtube_dl/YoutubeDL.py`](https://github.com/ytdl-org/youtube-dl/blob/main/youtube_dl/YoutubeDL.py) to parse, compile, and execute filter expressions at runtime.

### How do I filter videos by file size or duration?

Use numeric comparison operators within your filter string, such as `duration > 60` for videos longer than one minute or `filesize <= 5MiB` for files under five mebibytes. These expressions are parsed by `match_filter_func` in [`youtube_dl/utils.py`](https://github.com/ytdl-org/youtube-dl/blob/main/youtube_dl/utils.py) and evaluated against the numeric values in each video's metadata dictionary.

### Can I combine multiple conditions in a single match-filter?

Yes, join conditions with the `&` operator to enforce logical AND semantics, such as `view_count > 1000 & uploader = "Channel Name"`. The parsing logic in [`youtube_dl/utils.py`](https://github.com/ytdl-org/youtube-dl/blob/main/youtube_dl/utils.py) splits the expression on `&` and requires all parts to pass; no OR operator is provided, though you can chain multiple `--match-filter` invocations to achieve alternative logic.

### How does the match-filter system handle missing metadata fields?

By default, comparisons against missing fields fail and reject the video, but appending `?` to the operator makes the condition pass when the field is absent, such as `dislike_count <? 50`. This "unknown-value" tolerance is handled by `_match_one` in [`youtube_dl/utils.py`](https://github.com/ytdl-org/youtube-dl/blob/main/youtube_dl/utils.py), allowing filters to gracefully handle extractors that do not provide specific metadata fields.