make dev fails on macOS with ModuleNotFoundError: No module named '_tkinter'

[wy-hua]

Environment

• macOS (Apple Silicon / arm64)
• Python 3.12 via Homebrew
• uv for dependency management

Steps to Reproduce

1. Clone the repo on a fresh macOS setup
2. Run make dev

Error

Traceback (most recent call last):
  File "<frozen runpy>", line 198, in _run_module_as_main
  File "<frozen runpy>", line 88, in _run_code
  File ".../pyclashbot/__main__.py", line 32, in <module>
    from pyclashbot.bot.worker import WorkerProcess
  ...
  File "/opt/homebrew/Cellar/python@3.12/3.12.8/Frameworks/Python.framework/Versions/3.12/lib/python3.12/tkinter/__init__.py", line 38, in <module>
    import _tkinter # If this fails your Python may not be configured for Tk
    ^^^^^^^^^^^^^^^
ModuleNotFoundError: No module named '_tkinter'

Root Cause

Homebrew's python@3.12 bottle is not compiled with Tcl/Tk support by default. The _tkinter C extension is distributed separately via the python-tk@3.12 formula.

Fix

brew install python-tk@3.12

After installing, make dev works correctly.

Suggestion

Consider adding a note to the README or CLAUDE.md macOS setup instructions:

brew install python-tk@3.12   # required for tkinter (GUI)

[wy-hua]

Follow-up: Second crash after fixing _tkinter

After resolving the _tkinter issue, make dev crashes with a second error:

_tkinter.TclError: invalid command name ".!notebook.!frame2.!frame.!frame.!combobox.popdown.f.l"

Full traceback:

File "pyclashbot/__main__.py", line 127, in load_settings
    ui.set_all_values(loaded)
File "pyclashbot/interface/ui.py", line 179, in set_all_values
    self._apply_theme(theme_value)
File "pyclashbot/interface/ui.py", in _apply_theme
    self._style.theme_use(selected)
  ... (ttkbootstrap internals) ...
_tkinter.TclError: invalid command name ".!notebook.!frame2.!frame.!frame.!combobox.popdown.f.l"

Root Cause

ttkbootstrap's theme_use() broadcasts a message to all registered combobox widgets to update their popdown style. However, the popdown widget (.popdown.f.l) only exists after the user has opened the dropdown at least once. Calling theme_use() during startup — before any dropdown has been interacted with — causes a TclError on the non-existent popdown widget.

Fix

Wrap self._style.theme_use(selected) in a try/except tk.TclError in _apply_theme (pyclashbot/interface/ui.py):

def _apply_theme(self, theme_name: str, skip_variable_update: bool = False) -> None:
    available = tuple(self._style.theme_names())
    selected = theme_name if theme_name in available else self.DEFAULT_THEME
    if selected not in available and available:
        selected = available[0]
    if not skip_variable_update or self.theme_var.get() != selected:
        self._suspend_traces += 1
        try:
            self.theme_var.set(selected)
        finally:
            self._suspend_traces -= 1
    try:
        self._style.theme_use(selected)
    except tk.TclError:
        pass
    self._refresh_theme_colours()

The theme still applies correctly — the only thing silenced is the spurious error from ttkbootstrap trying to style a widget that doesn't exist yet. This is a known ttkbootstrap behaviour when theme_use() is called before any combobox popdown has been opened.

[martinmiglio]

Are you willing to open PRs for fixes on these issues? I would recommend adding the macOS dev setup instructions to CONTRIBUTING.md

[wy-hua]

yes