deepfakes/faceswap · error · FaceswapError

TkInter not found

Error message

TkInter not found

What it means

GUI display check in lib/cli/launcher.py: on non-Windows systems, launching GUI mode requires a DISPLAY environment variable. If DISPLAY is unset (and OS is not 'nt'), FaceswapError is raised; on macOS it additionally points to XQuartz.

Source

Thrown at lib/cli/launcher.py:152

        Raises
        ------
        FaceswapError
            If tkinter cannot be imported
        """
        try:
            import tkinter  # noqa pylint:disable=unused-import,import-outside-toplevel
        except ImportError as err:
            logger.error("It looks like TkInter isn't installed for your OS, so the GUI has been "
                         "disabled. To enable the GUI please install the TkInter application. You "
                         "can try:")
            logger.info("Anaconda: conda install tk")
            logger.info("Windows/macOS: Install ActiveTcl Community Edition from "
                        "http://www.activestate.com")
            logger.info("Ubuntu/Mint/Debian: sudo apt install python3-tk")
            logger.info("Arch: sudo pacman -S tk")
            logger.info("CentOS/Redhat: sudo yum install tkinter")
            logger.info("Fedora: sudo dnf install python3-tkinter")
            raise FaceswapError("TkInter not found") from err

    @classmethod
    def _check_display(cls) -> None:
        """Check whether there is a display to output the GUI to.

        If running on Windows then it is assumed that we are not running in headless mode

        Raises
        ------
        FaceswapError
            If a DISPLAY environmental variable cannot be found
        """
        if not os.environ.get("DISPLAY", None) and os.name != "nt":
            if platform.system() == "Darwin":
                logger.info("macOS users need to install XQuartz. "
                            "See https://support.apple.com/en-gb/HT201341")
            raise FaceswapError("No display detected. GUI mode has been disabled.")

View on GitHub (pinned to f530cb7508)

Solutions

1. Use CLI subcommands (extract/train/convert) which need no display
2. SSH with X forwarding (`ssh -X`) or set DISPLAY to your X server (e.g. DISPLAY=:0 or host.docker.internal:0 for containers)
3. On macOS install XQuartz as the log message suggests

Example fix

# before
ssh user@gpuserver
python faceswap.py          # -> No display detected. GUI mode has been disabled.

# after
# option 1: no GUI needed
python faceswap.py train -h
# option 2: forward X
ssh -X user@gpuserver && python faceswap.py

def gui_available():
    try:
        import tkinter  # noqa
        return True
    except ImportError:
        return False

if not gui_available():
    raise SystemExit("tkinter missing - install python3-tk or use CLI subcommands")

def has_tk() -> bool:
    """True when the TkInter runtime importable in this interpreter."""
    try:
        import tkinter  # noqa: F401
        return True
    except ImportError:
        return False

try:
    import tkinter  # noqa
except ImportError as err:
    print("GUI disabled; use: python faceswap.py <command> -h")
    raise SystemExit(1) from err

When it happens

Trigger: Running `faceswap.py gui` over SSH without X forwarding, inside a Docker container or headless server/Wayland session where DISPLAY is not exported; TkInter itself is installed, so the earlier import check passes and this check fires instead.

Common situations: Training/extracting on a remote GPU box via SSH; GUI scripts inside containers; WSL without an X server; CI pipelines that accidentally invoke the default gui command.

Related errors

• Dataclass params {sorted(required)} should be a subset of di
• An unhandled exception occurred reading from the Nvidia Mach
• Landmark based masks cannot be created for {self._landmark_t
• There is a mismatch between the number of frames found in th
• Alignments file not found at {self._file}

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