deepfakes/faceswap · error · ValueError

Dataclass params {sorted(required)} should be a subset of di

Error message

Dataclass params {sorted(required)} should be a subset of dictionary keys {sorted(inbound)}

What it means

Faceswap's GUI is TkInter-based. When the 'gui' command is requested, lib/cli/launcher.py tries `import tkinter`; on ImportError it logs per-OS install hints and re-raises as FaceswapError('TkInter not found').

Source

Thrown at lib/align/objects.py:178

    @classmethod
    def from_dict(cls, data_dict: dict[str, T.Any]) -> T.Self:
        """Load the contents from a serialized python dict into this dataclass

        Parameters
        ----------
        data_dict
            The data to load into the dataclass
        """
        inbound = set(data_dict)
        all_fields = set(f.name for f in fields(cls))
        required = set(f.name for f in fields(cls)
                       if f.default is MISSING and f.default_factory is MISSING)
        if not inbound.issubset(all_fields):
            raise ValueError(f"Dictionary keys {sorted(inbound)} should be a subset of dataclass "
                             f"params {sorted(all_fields)}")
        if not required.issubset(inbound):
            raise ValueError(f"Dataclass params {sorted(required)} should be a subset of "
                             f"dictionary keys {sorted(inbound)}")
        type_hints = T.get_type_hints(cls)
        kwargs: dict[str, T.Any] = {}
        for f in fields(cls):
            if f.name not in data_dict:
                continue
            field_type = type_hints.get(f.name)
            val = data_dict[f.name]
            converted = cls._convert_dtype(field_type, val)
            if converted is not None:
                kwargs[f.name] = converted
                continue
            if isinstance(val, dict):
                kwargs[f.name] = cls._parse_dict(field_type, val)
                continue
            if isinstance(val, (list, tuple)):
                kwargs[f.name] = cls._parse_list(field_type, val)
                continue

View on GitHub (pinned to f530cb7508)

Solutions

1. Install tk for your platform: Ubuntu/Debian `sudo apt install python3-tk`, Arch `sudo pacman -S tk`, Fedora `sudo dnf install python3-tkinter`, conda `conda install tk`
2. If you don't need the GUI, run a CLI command explicitly (e.g. `python faceswap.py extract ...`) instead of GUI mode
3. Verify with `python -c "import tkinter"` in the same interpreter/env you launch faceswap with

Example fix

# before
python faceswap.py          # launches GUI -> FaceswapError: TkInter not found

# after (Ubuntu/Debian)
sudo apt install python3-tk
python faceswap.py
# or skip the GUI entirely
python faceswap.py extract --help

from dataclasses import fields

from dataclasses import fields, MISSING

def missing_required(cls, data):
    req = {f.name for f in fields(cls)
           if f.default is MISSING and f.default_factory is MISSING}
    return req - set(data)

missing = missing_required(MyDataclass, payload)
assert not missing, f"payload lacks: {missing}"

try:
    obj = MyDataclass.from_dict(payload)
except ValueError as err:
    if "should be a subset of dictionary keys" in str(err):
        for k in missing_required(MyDataclass, payload):
            payload[k] = DEFAULTS[k]
        obj = MyDataclass.from_dict(payload)
    else:
        raise

When it happens

Trigger: Running `faceswap.py gui` (or python faceswap.py with no args, which defaults to GUI) in a Python environment where the tkinter module is not installed (missing tk package, headless python build, some conda/miniconda images).

Common situations: Docker/CI images built on python:slim which omit tk; minimal Linux python installs; a conda env created without tk; macOS system python without ActiveTcl.

Related errors

• TkInter not found
• Hex color codes should start with a '#' and be 6 characters
• An unhandled exception occurred initializing the device via
• An unhandled exception occurred reading from the Nvidia Mach
• {arch}' is not compatible with your version of Keras. The mi

AI-assisted analysis of deepfakes/faceswap@f530cb7508 (2026-08-15). Data as JSON: /api/errors/3c075eebf3aa4099. Report an issue: GitHub.