# How to Configure Batch Processing and Queue Sizes for Optimal Performance in Faceswap

> Optimize Faceswap performance by configuring batch processing and queue sizes. Learn expert settings for GPU VRAM and prevent memory bloat for faster conversions.

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

---

**Enable batch mode with the `-B` flag, set `--convert-batchsize` based on your GPU VRAM (4–8 for ≤4GB, 8–16 for 8GB, 16–32 for ≥12GB), and cap queue sizes to 2–4× the batch size using `-Q` to prevent memory bloat while maintaining pipeline throughput.**

The Faceswap deep learning pipeline processes thousands of frames through extraction, alignment, and conversion stages. To maximize throughput and prevent bottlenecks when working with the `deepfakes/faceswap` repository, you must configure batch processing and queue sizes for optimal performance based on your hardware constraints and the specific stage being executed.

## Understanding Batch Processing in Faceswap

Batch processing controls how many items are collected before a model is invoked, such as a face-swap or conversion network. By default, Faceswap processes frames individually, which underutilizes GPU parallelism. Enabling batch mode groups frames together for simultaneous inference.

### Where Batch Mode is Defined

All high-level tools share the same flag definition across the CLI tools. You can find the `-B` or `--batch-mode` argument in files such as [`tools/alignments/cli.py`](https://github.com/deepfakes/faceswap/blob/main/tools/alignments/cli.py), [`tools/mask/cli.py`](https://github.com/deepfakes/faceswap/blob/main/tools/mask/cli.py), and [`tools/sort/cli.py`](https://github.com/deepfakes/faceswap/blob/main/tools/sort/cli.py):

```python

# Example from tools/alignments/cli.py

{
    "opts": ("-B", "--batch-mode"),
    "dest": "batch_mode",
    "action": "store_true",
    "help": "Run the job in batch mode (collect many frames before processing)."
}

```

### Enabling Batch Mode via CLI

Add `-B` (or `--batch-mode`) when launching any job to activate batch processing. When active, tools internally call `read_image_meta_batch` from [`lib/image.py`](https://github.com/deepfakes/faceswap/blob/main/lib/image.py) to collect **N** frames before inference:

```bash
python scripts/convert.py -i input_folder -o output_folder -B
python tools/alignments/cli.py -i video.mp4 -B
python tools/mask/cli.py -i aligned_folder -B

```

## Configuring Batch Sizes for GPU Memory

The effective batch size determines how many frames travel through the model simultaneously. This value is constrained by available VRAM and configured through the `convert_batchsize` setting.

### The convert_batchsize Configuration

The maximum batch size per GPU is stored in the training configuration as `convert_batchsize`. In [`plugins/train/train_config.py`](https://github.com/deepfakes/faceswap/blob/main/plugins/train/train_config.py), this is defined as a `ConfigItem`:

```python

# plugins/train/train_config.py

convert_batchsize = ConfigItem(
    "convert_batchsize",
    default=8,
    doc="Maximum number of frames to feed to the conversion model at once."
)

```

You can override this at runtime with the `--convert-batchsize` CLI option exposed by [`scripts/convert.py`](https://github.com/deepfakes/faceswap/blob/main/scripts/convert.py).

### GPU-Aware Batch Size Calculation

The actual batch size used at runtime is clipped to available device memory. In [`scripts/convert.py`](https://github.com/deepfakes/faceswap/blob/main/scripts/convert.py), the `_get_batchsize()` method implements this logic:

```python

# scripts/convert.py

def _get_batchsize(self, queue_size: int) -> int:
    batchsize = 1 if is_cpu else mod_cfg.convert_batchsize()
    batchsize = min(queue_size, batchsize)
    return batchsize

```

This ensures the batch size never exceeds the queue size or available VRAM.

### Recommended Batch Sizes by VRAM

Select a `--convert-batchsize` value that fits comfortably within your GPU memory to avoid out-of-memory errors while maximizing utilization:

- **≤4 GB VRAM**: Use batch size **4–8**. This fits comfortably within limited memory and prevents OOM crashes during high-resolution conversions.
- **8 GB VRAM**: Use batch size **8–16**. This utilizes most of the available memory without exceeding typical overhead limits.
- **≥12 GB VRAM**: Use batch size **16–32**. Larger batches improve GPU utilization and reduce kernel launch overhead on high-end cards.

Set the value in [`config.ini`](https://github.com/deepfakes/faceswap/blob/main/config.ini) or pass it on the command line:

```bash
python scripts/convert.py -i in -o out -B --convert-batchsize 16

```

## Managing Queue Sizes for Pipeline Throughput

Queue sizes control the maximum number of items that can sit in intermediate buffers before producers block. Proper queue sizing prevents memory bloat while ensuring the GPU never starves for data.

### How Queues Work in Faceswap

The pipeline uses named `EventQueue` instances created via `lib/queue_manager._QueueManager.add_queue()`. By default, queues are created with `maxsize=0` (unlimited), which can consume excessive RAM when consumers are slower than producers.

Key files implementing queue management include:
- [`lib/queue_manager.py`](https://github.com/deepfakes/faceswap/blob/main/lib/queue_manager.py) – Core queue implementation
- [`scripts/convert.py`](https://github.com/deepfakes/faceswap/blob/main/scripts/convert.py) – Queue creation for conversion pipeline
- [`plugins/extract/pipeline.py`](https://github.com/deepfakes/faceswap/blob/main/plugins/extract/pipeline.py) – Queue usage in extraction
- [`tools/preview/preview.py`](https://github.com/deepfakes/faceswap/blob/main/tools/preview/preview.py) – Preview queue handling

### Setting Queue Size Limits

Most tools expose the `-Q` or `--queue-size` CLI flag, which propagates to the internal `_queue_size` attribute used when calling `add_queue()`:

```python

# Example from scripts/convert.py

queue_manager.add_queue(qname, self._queue_size)  # self._queue_size defaults to 32

```

Set the queue size at runtime:

```bash
python scripts/convert.py -i in -o out -B -Q 64

```

### Optimal Queue Sizing Strategy

Size your queues relative to the batch size to balance memory usage against pipeline stalls:

- **Input reader stage**: Set to **2× the batch size**. This prevents the GPU from starving while the CPU reads and decodes images.
- **Model inference stage**: Set to **1× the batch size**. The model consumes batches immediately, so minimal buffering is required.
- **Post-processing stage**: Set to **2–4× the batch size**. Disk I/O operations can be slower than GPU inference; extra buffering smooths out write spikes.

If you encounter "MemoryError" or "Queue full" warnings, reduce the queue size (`-Q`) or increase the batch size if VRAM permits. If the GPU utilization drops to zero between batches, increase the queue size to allow the CPU to stay ahead of the GPU.

## Complete Configuration Example

The following workflow demonstrates optimal settings for a system with 8 GB VRAM:

```bash

# 1️⃣ Extract faces (high-resolution, GPU-heavy)

python scripts/extract.py -i video.mp4 -o faces_dir -B \
    --convert-batchsize 24 -Q 48

# 2️⃣ Align the extracted faces (CPU-bound, can use many workers)

python tools/alignments/cli.py -i faces_dir -o aligned_dir -B \
    --processes 8 -Q 64

# 3️⃣ Convert (swap) using the trained model

python scripts/convert.py -i aligned_dir -o swapped_dir -B \
    --convert-batchsize 16 -Q 32

```

- **Batch mode** (`-B`) ensures each step processes groups of frames rather than one-by-one.
- **`--convert-batchsize`** tailors the GPU workload to your hardware capabilities.
- **`-Q`** caps each intermediate queue to prevent runaway RAM consumption while maintaining pipeline flow.

## Key Source Code References

The following files implement the batch and queue management systems described above:

- **[`lib/queue_manager.py`](https://github.com/deepfakes/faceswap/blob/main/lib/queue_manager.py)** – Core `EventQueue` implementation and `_QueueManager.add_queue()` method for creating bounded queues.
- **[`lib/image.py`](https://github.com/deepfakes/faceswap/blob/main/lib/image.py)** – `read_image_meta_batch()` function used when batch mode is active.
- **[`plugins/train/train_config.py`](https://github.com/deepfakes/faceswap/blob/main/plugins/train/train_config.py)** – Contains `convert_batchsize` configuration item definition.
- **[`scripts/convert.py`](https://github.com/deepfakes/faceswap/blob/main/scripts/convert.py)** – Implements `_get_batchsize()` for GPU-aware batch calculation and queue creation via `add_queue()`.
- **[`tools/alignments/cli.py`](https://github.com/deepfakes/faceswap/blob/main/tools/alignments/cli.py)**, **[`tools/mask/cli.py`](https://github.com/deepfakes/faceswap/blob/main/tools/mask/cli.py)**, **[`tools/sort/cli.py`](https://github.com/deepfakes/faceswap/blob/main/tools/sort/cli.py)** – Define the `-B`/`--batch-mode` CLI flags.
- **[`plugins/extract/pipeline.py`](https://github.com/deepfakes/faceswap/blob/main/plugins/extract/pipeline.py)** – Demonstrates queue usage in the extraction pipeline.

## Summary

- **Enable batch processing** using the `-B` flag to group frames for parallel GPU inference rather than processing them sequentially.
- **Size batches to VRAM** by setting `--convert-batchsize` to 4–8 for ≤4GB GPUs, 8–16 for 8GB GPUs, or 16–32 for ≥12GB GPUs.
- **Bound queue sizes** with `-Q` set to 2–4× the batch size to prevent memory bloat while ensuring the GPU never starves for data.
- **Scale CPU workers** using `--processes` for CPU-bound stages like alignment, independent of GPU batch settings.

## Frequently Asked Questions

### What is the default batch size in Faceswap?

The default batch size is **1** when running on CPU, or the value specified in `convert_batchsize` (default **8**) when using a GPU. However, the actual value is clipped by the `_get_batchsize()` method in [`scripts/convert.py`](https://github.com/deepfakes/faceswap/blob/main/scripts/convert.py) to ensure it fits within available VRAM and does not exceed the queue size.

### How do I prevent out-of-memory errors during conversion?

Reduce the `--convert-batchsize` value to match your GPU's VRAM capacity. For GPUs with 4GB or less, use values between 4 and 8. Additionally, ensure queue sizes are bounded using `-Q` to prevent unlimited memory growth in intermediate buffers. If errors persist, disable batch mode entirely by omitting the `-B` flag.

### Should I use the same queue size for all pipeline stages?

No, different stages require different queue sizes relative to the batch size. Set input reader queues to **2×** the batch size to prevent GPU starvation, model inference queues to **1×** the batch size since consumption is immediate, and post-processing queues to **2–4×** the batch size to accommodate slower disk I/O operations.

### Does batch mode work with CPU-only setups?

Yes, batch mode functions on CPU-only systems, but the batch size defaults to **1** regardless of configuration settings, as seen in the `_get_batchsize()` logic in [`scripts/convert.py`](https://github.com/deepfakes/faceswap/blob/main/scripts/convert.py). CPU processing does not benefit from larger batches in the same way GPUs do, so enabling batch mode primarily helps standardize pipeline behavior across hardware types.