# How to Configure Face Detection and Alignment in the FaceSwap Extract Process

> Learn how to configure face detection and alignment in FaceSwap extract using CLI arguments. Dynamically load plugin classes for efficient processing. Master your deepfake extractions.

- Repository: [deepfakes/faceswap](https://github.com/deepfakes/faceswap)
- Tags: how-to-guide
- Published: 2026-03-06

---

**Face detection and alignment in FaceSwap are configured via the `-D/--detector` and `-A/--aligner` CLI arguments, which dynamically load plugin classes from `plugins/extract/detect/` and `plugins/extract/align/` through the `PluginLoader` system.**

The extraction pipeline in the `deepfakes/faceswap` repository relies on a modular plugin architecture to locate faces and determine their orientation. When you configure face detection and alignment settings, you are selecting specific neural network models that run sequentially—first finding the face boundary box, then predicting facial landmarks. This configuration can be performed via command-line arguments when running `faceswap.py extract` or programmatically through the Python API.

## Understanding the Plugin Architecture

The extraction system separates concerns into two distinct plugin types managed by the `Extractor` class in [`plugins/extract/pipeline.py`](https://github.com/deepfakes/faceswap/blob/main/plugins/extract/pipeline.py).

### Detector Plugins

**Detectors** implement the base class `plugins.extract.detect._base.Detector` and are responsible for locating faces within a frame. The system provides different defaults based on hardware availability:

- **GPU systems**: `s3fd` (Single Shot MultiBox Detector)
- **CPU systems**: `mtcnn` (Multi-task Cascaded Convolutional Networks)

Other available detectors include `cv2-dnn` and `external`, located in `plugins/extract/detect/`.

### Aligner Plugins

**Aligners** implement `plugins.extract.align._base.Aligner` and predict facial landmarks (typically 68 or 81 points) to normalize face orientation:

- **GPU systems**: `fan` (Face Alignment Network)
- **CPU systems**: `cv2-dnn` (OpenCV DNN implementation)

These reside in `plugins/extract/align/` and are instantiated based on the `-A` argument.

## Command-Line Configuration

The CLI arguments are defined in [`lib/cli/args_extract_convert.py`](https://github.com/deepfakes/faceswap/blob/main/lib/cli/args_extract_convert.py) within the `ExtractArgs` class. The `-D/--detector` and `-A/--aligner` options use `PluginLoader.get_available_extractors()` to populate valid choices dynamically.

```python

# lib/cli/args_extract_convert.py

argument_list.append({
    "opts": ("-D", "--detector"),
    "action": Radio,
    "type": str.lower,
    "default": default_detector,
    "choices": PluginLoader.get_available_extractors("detect"),
    "group": _("Plugins"),
    "help": _("Detector to use …")
})
argument_list.append({
    "opts": ("-A", "--aligner"),
    "action": Radio,
    "type": str.lower,
    "default": default_aligner,
    "choices": PluginLoader.get_available_extractors("align"),
    "group": _("Plugins"),
    "help": _("Aligner to use …")
})

```

To run extraction with specific plugins:

```bash

# Default GPU configuration (s3fd + fan)

python3 faceswap.py extract -i /data/input -o /data/output

# CPU-optimized configuration (mtcnn + cv2-dnn)

python3 faceswap.py extract -i /data/input -o /data/output \
    -D mtcnn -A cv2-dnn

```

## Programmatic Configuration

You can configure the extraction pipeline directly in Python by constructing an `argparse.Namespace` and passing it to the `Extract` class from [`scripts/extract.py`](https://github.com/deepfakes/faceswap/blob/main/scripts/extract.py):

```python
from argparse import Namespace
from scripts.extract import Extract

# Configure arguments programmatically

args = Namespace(
    input_dir="/data/input",
    output_dir="/data/output",
    detector="mtcnn",          # Custom detector

    aligner="cv2-dnn",         # Custom aligner

    maskers=[],                # Default maskers

    # … additional arguments as needed …

)

# Initialize and run extraction

extractor = Extract(args)
extractor.process()

```

## Pipeline Initialization Deep Dive

The `Extractor` class in [`plugins/extract/pipeline.py`](https://github.com/deepfakes/faceswap/blob/main/plugins/extract/pipeline.py) handles the instantiation of selected plugins through the `_load_detect` and `_load_align` methods.

### Loading the Detector

The `_load_detect` method resolves the detector name via `PluginLoader.get_detector()` and handles special logic for external aligners:

```python

# plugins/extract/pipeline.py

def _load_detect(self, detector, aligner, rotation, min_size, configfile):
    if detector is None or detector.lower() == "none":
        return None
    detector_name = detector.replace("-", "_").lower()
    # Force external detector if aligner is external but detector isn't

    if aligner == "external" and detector_name != "external":
        detector_name = aligner
    plugin = PluginLoader.get_detector(detector_name)(
        rotation=rotation,
        min_size=min_size,
        configfile=configfile,
        instance=self._instance)
    return plugin

```

### Loading the Aligner

Similarly, `_load_align` instantiates the aligner plugin:

```python

# plugins/extract/pipeline.py

def _load_align(self, aligner, configfile, normalize_method,
                re_feed, re_align, disable_filter):
    if aligner is None or aligner.lower() == "none":
        return None
    aligner_name = aligner.replace("-", "_").lower()
    plugin = PluginLoader.get_aligner(aligner_name)(
        configfile=configfile,
        normalize_method=normalize_method,
        re_feed=re_feed,
        re_align=re_align,
        disable_filter=disable_filter,
        instance=self._instance)
    return plugin

```

## Configuration Files and Plugin Options

Beyond CLI selection, each plugin exposes hardware-specific settings through [`config/extract.ini`](https://github.com/deepfakes/faceswap/blob/main/config/extract.ini). Detector options typically include `rotation` and `min_size`, while aligners support `normalize_method`, `re_feed`, `re_align`, and `disable_filter`.

To use a custom configuration file:

```bash
python3 faceswap.py extract -i /data/input -o /data/output \
    --configfile /path/to/custom_extract.ini

```

## Summary

- **Face detection and alignment** in FaceSwap are handled by swappable plugins loaded via `PluginLoader` according to the `deepfakes/faceswap` source code.
- **Default selections** are hardware-dependent: `s3fd`/`fan` for GPU, `mtcnn`/`cv2-dnn` for CPU.
- **CLI configuration** uses `-D/--detector` and `-A/--aligner` arguments defined in [`lib/cli/args_extract_convert.py`](https://github.com/deepfakes/faceswap/blob/main/lib/cli/args_extract_convert.py).
- **Programmatic configuration** requires passing a `Namespace` object with `detector` and `aligner` attributes to the `Extract` class.
- **Pipeline initialization** occurs in [`plugins/extract/pipeline.py`](https://github.com/deepfakes/faceswap/blob/main/plugins/extract/pipeline.py), where `_load_detect` and `_load_align` instantiate the selected plugins with configuration from [`config/extract.ini`](https://github.com/deepfakes/faceswap/blob/main/config/extract.ini).

## Frequently Asked Questions

### What are the default face detection and alignment plugins in FaceSwap?

FaceSwap automatically selects plugins based on your hardware configuration. For GPU systems, the defaults are `s3fd` (Single Shot MultiBox Detector) for detection and `fan` (Face Alignment Network) for alignment. For CPU-only systems, the defaults switch to `mtcnn` (Multi-task Cascaded Convolutional Networks) for detection and `cv2-dnn` for alignment.

### How do I switch to a CPU-friendly detector when running extraction?

Pass the `-D` or `--detector` flag with the value `mtcnn` or `cv2-dnn` when launching the extraction command. For example: `python3 faceswap.py extract -i /data/input -o /data/output -D mtcnn -A cv2-dnn`. This bypasses the GPU-optimized defaults and loads the CPU-efficient implementations from [`plugins/extract/detect/mtcnn.py`](https://github.com/deepfakes/faceswap/blob/main/plugins/extract/detect/mtcnn.py) and [`plugins/extract/align/cv2_dnn.py`](https://github.com/deepfakes/faceswap/blob/main/plugins/extract/align/cv2_dnn.py).

### Can I use external face detection models with FaceSwap?

Yes. FaceSwap supports an `external` detector and aligner option designed for integration with external systems. When you specify `external` for the aligner via `-A external`, the pipeline automatically forces the detector to `external` as well if it isn't already set, as implemented in the `_load_detect` method in [`plugins/extract/pipeline.py`](https://github.com/deepfakes/faceswap/blob/main/plugins/extract/pipeline.py). This allows you to inject custom detection logic while maintaining the standard extraction workflow.

### Where are the plugin-specific settings for detectors and aligners stored?

Per-plugin configuration options are stored in [`config/extract.ini`](https://github.com/deepfakes/faceswap/blob/main/config/extract.ini). Each detector and aligner defines its own section in this file, controlling parameters such as `rotation`, `min_size` for detectors, and `normalize_method`, `re_feed`, `re_align`, and `disable_filter` for aligners. You can override the default configuration file path by passing `--configfile /path/to/custom.ini` when running the extract command.