# How to Use the abx-dl --plugins Option to Select Specific Plugins for Downloads

> Master the abx-dl --plugins option. Learn to specify download plugins like wget, ytdlp, and git for targeted ArchiveBox downloads and improve your workflow today.

- Repository: [ArchiveBox/abx-dl](https://github.com/archivebox/abx-dl)
- Tags: how-to-guide
- Published: 2026-02-25

---

**Use the `-p` or `--plugins` flag followed by a comma-separated list of plugin names (e.g., `--plugins=wget,ytdlp,git`) to limit abx-dl to specific ArchiveBox plugins instead of running all discovered ones.**

The `abx-dl` command-line tool from the `archivebox/abx-dl` repository enables you to download content using modular ArchiveBox plugins. By default, the tool executes every discovered plugin, but you can use the **abx-dl --plugins option** to select specific plugins for a download, improving efficiency and customizing output behavior.

## How the abx-dl --plugins Option Works Internally

### Plugin Discovery in cli.py

When the CLI initializes, it discovers every plugin under `abx_dl/plugins` and stores them in `ctx.obj['plugins']` according to the source code in [`abx_dl/cli.py`](https://github.com/archivebox/abx-dl/blob/main/abx_dl/cli.py) (lines 58-60). This discovery happens before any command execution, ensuring all available plugins are known upfront.

### Parsing the Comma-Separated Input

The `dl` command defines the option `--plugins` (short form `-p`) as a comma-separated string parameter in [`abx_dl/cli.py`](https://github.com/archivebox/abx-dl/blob/main/abx_dl/cli.py) (lines 64-66). This design allows you to pass multiple plugin names in a single argument rather than repeating flags.

### Selection and Filtering Logic

Inside the `dl` function, the input string is split on commas, stripped of whitespace, and stored as a `selected` list (lines 84-90 in [`abx_dl/cli.py`](https://github.com/archivebox/abx-dl/blob/main/abx_dl/cli.py)). This list passes to the executor in [`abx_dl/executor.py`](https://github.com/archivebox/abx-dl/blob/main/abx_dl/executor.py), which forwards it to the `filter_plugins` function in [`abx_dl/plugins.py`](https://github.com/archivebox/abx-dl/blob/main/abx_dl/plugins.py) (lines 77-88). The `filter_plugins` function returns only plugins whose names match the supplied list, effectively limiting the download to your specified subset.

## Practical Usage Examples for Selecting Plugins

### Default Behavior (All Plugins)

When you omit the flag, **all discovered plugins** run automatically:

```bash
abx-dl "https://example.com"

```

### Select Specific Plugins with --plugins

Pass a comma-separated list of plugin names (no spaces required, though whitespace is stripped):

```bash
abx-dl --plugins=wget,ytdlp,git "https://example.com"

```

Use the short form for brevity:

```bash
abx-dl -p wget,ytdlp,git "https://example.com"

```

The flag accepts any plugin name present in the `abx_dl/plugins` directory, such as `wget`, `ytdlp`, or `git`.

### Using the Flag in Python Scripts

You can invoke the tool via `subprocess` while dynamically constructing the plugin list:

```python
import subprocess

url = "https://example.com"
plugins = "wget,ytdlp"
subprocess.run(["abx-dl", f"--plugins={plugins}", url], check=True)

```

### Combining with Other CLI Options

The `--plugins` flag works alongside other arguments like `--output` and `--timeout`:

```bash
abx-dl -p wget,ytdlp \
        --output=/tmp/archive \
        --timeout=120 \
        "https://example.com"

```

## Key Source Files and Implementation Details

Understanding the following files helps when debugging or extending the `--plugins` functionality:

- **[`abx_dl/cli.py`](https://github.com/archivebox/abx-dl/blob/main/abx_dl/cli.py)** – Defines the `--plugins` option, parses the comma-separated list in the `dl` command, and passes the `selected` plugins to the download generator (lines 62-90).
- **[`abx_dl/plugins.py`](https://github.com/archivebox/abx-dl/blob/main/abx_dl/plugins.py)** – Contains the `discover_plugins` function for initial loading, the `filter_plugins` function (lines 77-88) that implements the selection logic, and the `Plugin` data class that represents individual plugins.
- **[`abx_dl/executor.py`](https://github.com/archivebox/abx-dl/blob/main/abx_dl/executor.py)** – Runs the actual download workflow; receives the filtered plugin set from [`cli.py`](https://github.com/archivebox/abx-dl/blob/main/cli.py) and executes each plugin's hooks according to the filtered sequence.

## Summary

- Use `--plugins` or `-p` followed by comma-separated names to limit which plugins run during a download.
- Omitting the flag runs **all discovered plugins** automatically.
- The filtering occurs in `filter_plugins` within [`abx_dl/plugins.py`](https://github.com/archivebox/abx-dl/blob/main/abx_dl/plugins.py) after the CLI parses and splits the input string in [`abx_dl/cli.py`](https://github.com/archivebox/abx-dl/blob/main/abx_dl/cli.py).
- Plugin names must match those discovered in the `abx_dl/plugins` directory at runtime.
- The implementation automatically handles whitespace around commas when parsing the list.

## Frequently Asked Questions

### What happens if I don't specify the --plugins flag?

If you omit the `--plugins` option, **all discovered plugins** are used for the download. The tool automatically discovers every plugin under `abx_dl/plugins` during CLI initialization (lines 58-60 in [`abx_dl/cli.py`](https://github.com/archivebox/abx-dl/blob/main/abx_dl/cli.py)) and executes them without filtering.

### Can I use spaces in the comma-separated plugin list?

Yes, the implementation in [`abx_dl/cli.py`](https://github.com/archivebox/abx-dl/blob/main/abx_dl/cli.py) automatically strips whitespace from each plugin name after splitting the comma-separated string (lines 84-90). Both `--plugins=wget, ytdlp` and `--plugins=wget,ytdlp` are valid and resolve to the same plugin selection.

### How do I find which plugin names are available?

Available plugin names correspond to the subdirectories or modules within the `abx_dl/plugins` directory. The CLI discovers these at runtime via the `discover_plugins` function and stores them in the Click context object during initialization (lines 58-60 in [`abx_dl/cli.py`](https://github.com/archivebox/abx-dl/blob/main/abx_dl/cli.py)).

### Can I exclude specific plugins instead of including them?

The current implementation only supports an inclusion list via `--plugins`. To exclude specific plugins, you must specify all desired plugins explicitly, omitting the ones you wish to exclude. There is no built-in `--exclude-plugins` flag in the current version.