{"record":{"id":"342345d34208f61d","repo":"deepfakes/faceswap","slug":"tkinter-not-found","errorCode":null,"errorMessage":"TkInter not found","messagePattern":"TkInter not found","errorType":"exception","errorClass":"FaceswapError","httpStatus":null,"severity":"error","filePath":"lib/cli/launcher.py","lineNumber":152,"sourceCode":"        Raises\n        ------\n        FaceswapError\n            If tkinter cannot be imported\n        \"\"\"\n        try:\n            import tkinter  # noqa pylint:disable=unused-import,import-outside-toplevel\n        except ImportError as err:\n            logger.error(\"It looks like TkInter isn't installed for your OS, so the GUI has been \"\n                         \"disabled. To enable the GUI please install the TkInter application. You \"\n                         \"can try:\")\n            logger.info(\"Anaconda: conda install tk\")\n            logger.info(\"Windows/macOS: Install ActiveTcl Community Edition from \"\n                        \"http://www.activestate.com\")\n            logger.info(\"Ubuntu/Mint/Debian: sudo apt install python3-tk\")\n            logger.info(\"Arch: sudo pacman -S tk\")\n            logger.info(\"CentOS/Redhat: sudo yum install tkinter\")\n            logger.info(\"Fedora: sudo dnf install python3-tkinter\")\n            raise FaceswapError(\"TkInter not found\") from err\n\n    @classmethod\n    def _check_display(cls) -> None:\n        \"\"\"Check whether there is a display to output the GUI to.\n\n        If running on Windows then it is assumed that we are not running in headless mode\n\n        Raises\n        ------\n        FaceswapError\n            If a DISPLAY environmental variable cannot be found\n        \"\"\"\n        if not os.environ.get(\"DISPLAY\", None) and os.name != \"nt\":\n            if platform.system() == \"Darwin\":\n                logger.info(\"macOS users need to install XQuartz. \"\n                            \"See https://support.apple.com/en-gb/HT201341\")\n            raise FaceswapError(\"No display detected. GUI mode has been disabled.\")\n","sourceCodeStart":134,"sourceCodeEnd":170,"githubUrl":"https://github.com/deepfakes/faceswap/blob/f530cb7508ae670f6474f8a7d9c4df94705cf96b/lib/cli/launcher.py#L134-L170","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use CLI subcommands (extract/train/convert) which need no display","SSH with X forwarding (`ssh -X`) or set DISPLAY to your X server (e.g. DISPLAY=:0 or host.docker.internal:0 for containers)","On macOS install XQuartz as the log message suggests"],"exampleFix":"# before\nssh user@gpuserver\npython faceswap.py          # -> No display detected. GUI mode has been disabled.\n\n# after\n# option 1: no GUI needed\npython faceswap.py train -h\n# option 2: forward X\nssh -X user@gpuserver && python faceswap.py","handlingStrategy":"validation","validationCode":"def gui_available():\n    try:\n        import tkinter  # noqa\n        return True\n    except ImportError:\n        return False\n\nif not gui_available():\n    raise SystemExit(\"tkinter missing - install python3-tk or use CLI subcommands\")","typeGuard":"def has_tk() -> bool:\n    \"\"\"True when the TkInter runtime importable in this interpreter.\"\"\"\n    try:\n        import tkinter  # noqa: F401\n        return True\n    except ImportError:\n        return False","tryCatchPattern":"try:\n    import tkinter  # noqa\nexcept ImportError as err:\n    print(\"GUI disabled; use: python faceswap.py <command> -h\")\n    raise SystemExit(1) from err","preventionTips":["Install python3-tk/tk in dev images before first GUI launch","Default scripts to explicit CLI subcommands on servers/containers","Smoke-test `python -c 'import tkinter'` in CI for GUI-enabled builds"],"tags":["faceswap","gui","headless","display","ssh","docker"],"backgroundTag":null,"analyzedSha":"f530cb7508ae670f6474f8a7d9c4df94705cf96b","analyzedAt":"2026-08-15T02:59:26.626Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}