# How to Use the Faceswap GUI for Training and Conversion: Complete Workflow Guide

> Master the Faceswap GUI for training and conversion. This complete guide walks you through the workflow for effortless deepfake creation using the intuitive visual interface.

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

---

**The Faceswap GUI provides a Tkinter-based visual interface that wraps the underlying command-line tools, allowing users to configure training parameters and conversion settings through intuitive tabs while executing heavy GPU workloads in background processes.**

The deepfakes/faceswap project includes a comprehensive graphical interface that eliminates the need for complex terminal commands when training deep learning models or performing face swaps on media. This **Faceswap GUI** dynamically generates configuration panels from the codebase, manages subprocesses for resource-intensive tasks, and captures real-time logs in a built-in console. Understanding the relationship between the visual components and their underlying Python modules enables you to troubleshoot issues and customize workflows effectively.

## Architecture Overview

The Faceswap GUI operates as a thin wrapper around the core scripts located in `scripts/` and `plugins/`. When you execute [`scripts/gui.py`](https://github.com/deepfakes/faceswap/blob/main/scripts/gui.py), the application initializes a `FaceswapGui` object (a subclass of `tk.Tk` defined at lines 30-46) that constructs the main window, menubar, and paned interface.

Key architectural components include:

- **Configuration Management**: The [`lib/gui/gui_config.py`](https://github.com/deepfakes/faceswap/blob/main/lib/gui/gui_config.py) module handles `.ini` file parsing through `load_config()` and exposes available commands via `get_commands()`, which populates the tabbed notebook interface.
- **Command Notebook**: Located in [`lib/gui/command.py`](https://github.com/deepfakes/faceswap/blob/main/lib/gui/command.py), this dynamically generates tabs (Extract, Train, Convert) based on the command list retrieved from the configuration.
- **Process Management**: The `ProcessWrapper` class spawns separate Python processes when you initiate training or conversion, ensuring the Tkinter interface remains responsive during GPU-intensive operations.
- **Log Capture**: The `ConsoleOut` widget in [`lib/gui/display.py`](https://github.com/deepfakes/faceswap/blob/main/lib/gui/display.py) streams stdout and stderr from background processes into the GUI's lower console pane.

## Launching the Faceswap GUI

You can start the interface from the repository root using the entry point defined in [`scripts/gui.py`](https://github.com/deepfakes/faceswap/blob/main/scripts/gui.py). The `Gui.process()` method (lines 86-94) parses arguments, instantiates the main window, and enters the Tkinter main loop.

### Command-Line Launch

Execute the following from your terminal to start the GUI with default settings:

```bash
python3 scripts/gui.py

```

To use a custom configuration file containing default paths, fonts, or layout preferences:

```bash
python3 scripts/gui.py --configfile my_faceswap.ini

```

### Programmatic Launch

You can also embed the GUI launcher within another Python script by importing the `Gui` class and passing an argument namespace:

```python
from scripts.gui import Gui
import argparse

parser = argparse.ArgumentParser()
parser.add_argument('--debug', action='store_true')
parser.add_argument('--configfile', type=str, default=None)
args = parser.parse_args(['--debug'])

gui = Gui(args)  # Creates FaceswapGui internally

gui.process()    # Runs the Tkinter mainloop

```

## Training Models via the Faceswap GUI

The **Train** tab provides a visual frontend to the training pipeline implemented in [`plugins/train/training.py`](https://github.com/deepfakes/faceswap/blob/main/plugins/train/training.py). When configured, the GUI invokes trainer classes located in `plugins/train/trainer/` (such as [`original.py`](https://github.com/deepfakes/faceswap/blob/main/original.py)) through a background process.

### Step-by-Step Training Workflow

1. **Select the Train Tab**: The GUI generates this tab dynamically from the command list returned by `get_commands()` in [`lib/gui/gui_config.py`](https://github.com/deepfakes/faceswap/blob/main/lib/gui/gui_config.py).

2. **Configure Dataset**: Point to a folder containing aligned face images. The GUI calls `initialize_images()` to cache thumbnails for preview purposes.

3. **Choose Model Architecture**: Select from available trainers (e.g., *Original*, *DFaker*, *Lightweight*) via a dropdown populated by scanning `plugins/train/model/`.

4. **Set Hyperparameters**: Adjust epochs, batch size, and learning-rate warm-up through spin-box widgets. These values serialize to a temporary configuration consumed by [`plugins/train/training.py`](https://github.com/deepfakes/faceswap/blob/main/plugins/train/training.py).

5. **Initiate Training**: Clicking the **Start** button triggers `ProcessWrapper.start_task()`, which executes [`scripts/train.py`](https://github.com/deepfakes/faceswap/blob/main/scripts/train.py) in a subprocess. The `ConsoleOut` pane displays live TensorBoard events and iteration logs from [`plugins/train/trainer/_display.py`](https://github.com/deepfakes/faceswap/blob/main/plugins/train/trainer/_display.py).

6. **Monitor Progress**: The `StatusBar` updates with current iteration counts, while the console shows loss metrics. The process runs independently of the main GUI thread to prevent interface freezing.

7. **Session Persistence**: Upon completion or manual stopping, the GUI automatically calls `LastSession.save()` to preserve your configuration for subsequent training resumes.

### Example: Starting Training Programmatically

While the GUI handles this internally, the underlying subprocess call follows this pattern:

```python
from lib.gui import ProcessWrapper

wrapper = ProcessWrapper()
wrapper.start_task(['python', 'scripts/train.py',
                    '--model', 'original',
                    '--dataset', '/path/to/aligned',
                    '--epochs', '20'])

```

## Converting Media with the Faceswap GUI

The **Convert** tab interfaces with [`scripts/convert.py`](https://github.com/deepfakes/faceswap/blob/main/scripts/convert.py) and the core engine in [`lib/convert.py`](https://github.com/deepfakes/faceswap/blob/main/lib/convert.py) to apply trained models to images or videos. This process swaps faces in source media using the weights generated during training.

### Conversion Workflow

1. **Access the Convert Tab**: Like the Train tab, this is generated dynamically from `get_commands()` in the GUI configuration.

2. **Select Trained Model**: The model selector scans your *models* directory for `.h5` checkpoint files and lists available weights compatible with the selected architecture.

3. **Input Source Media**: Browse or drag-and-drop images and video files. The GUI generates preview thumbnails via `get_images()` to confirm correct file selection.

4. **Configure Output Options**: Set the output format, resolution, face-swap masking strength, and audio retention preferences through the options panel.

5. **Execute Conversion**: The **Convert** button launches [`scripts/convert.py`](https://github.com/deepfakes/faceswap/blob/main/scripts/convert.py) through `ProcessWrapper.start_task()`. Progress indicators and any errors stream to the `ConsoleOut` display in real-time.

6. **Review Results**: Converted media saves to your specified output directory, with the GUI providing direct access to open the destination folder upon completion.

### Example: Conversion Subprocess Call

The GUI constructs and executes commands similar to the following when you start conversion:

```python
wrapper.start_task(['python', 'scripts/convert.py',
                    '--model-dir', '/models',
                    '--model', 'original_128.h5',
                    '--input-dir', '/media/source',
                    '--output-dir', '/media/output'])

```

## Summary

The Faceswap GUI streamlines deep learning workflows by wrapping command-line functionality in a Tkinter interface:

- **Launch** the application via `python3 scripts/gui.py`, optionally specifying a custom configuration file with `--configfile`.
- **Train** models by configuring datasets and architectures in the Train tab, which executes [`plugins/train/training.py`](https://github.com/deepfakes/faceswap/blob/main/plugins/train/training.py) in a background `ProcessWrapper` while displaying logs via `ConsoleOut`.
- **Convert** media through the Convert tab, which invokes [`scripts/convert.py`](https://github.com/deepfakes/faceswap/blob/main/scripts/convert.py) and [`lib/convert.py`](https://github.com/deepfakes/faceswap/blob/main/lib/convert.py) to apply trained weights to source files.
- **Monitor** all operations through the built-in console and status bar without blocking the main UI thread.
- **Resume** work easily via automatic session saving through `LastSession.save()`.

## Frequently Asked Questions

### How do I launch the Faceswap GUI with a custom configuration file?

Pass the `--configfile` argument followed by the path to your `.ini` file when starting the application: `python3 scripts/gui.py --configfile my_config.ini`. The [`lib/gui/gui_config.py`](https://github.com/deepfakes/faceswap/blob/main/lib/gui/gui_config.py) module parses this file via `load_config()` to set default fonts, layout options, and command-specific presets before building the interface.

### What happens when I click the Start button in the Training tab?

Clicking **Start** invokes `ProcessWrapper.start_task()`, which spawns a separate Python process running [`scripts/train.py`](https://github.com/deepfakes/faceswap/blob/main/scripts/train.py) with your selected parameters. This separation keeps the Tkinter interface responsive while the trainer class (e.g., [`plugins/train/trainer/original.py`](https://github.com/deepfakes/faceswap/blob/main/plugins/train/trainer/original.py)) handles GPU-intensive optimization. Output streams to the `ConsoleOut` widget in [`lib/gui/display.py`](https://github.com/deepfakes/faceswap/blob/main/lib/gui/display.py).

### Can I run training and conversion simultaneously in the GUI?

Yes, because the GUI uses `ProcessWrapper` to spawn independent subprocesses for each operation, you can queue or run multiple tasks concurrently. However, be mindful of GPU memory limitations, as both processes will compete for the same graphics card resources unless configured to use different devices.

### Where does the GUI save my training session progress?

The GUI automatically calls `LastSession.save()` when training ends or is manually stopped, storing your configuration and current state. This allows you to resume training later by reloading the GUI, which reads the saved session and repopulates the Training tab with your previous dataset paths, model selection, and hyperparameters.