【已解决】ModuleNotFoundError: No module named ‘_tkinter‘

如果你在用macOS，且用homebrew安装了
Python 3.12.10 （路径是 /opt/homebrew/Cellar/python@3.12/...），
它没有带 tkinter，因此你会遇到：

ModuleNotFoundError: No module named '_tkinter'

---

你该怎么做？

1. 用 pyenv 安装 Python，并用 pyenv 的 Python 运行项目！

你的环境变量和虚拟环境都没问题，但Python 必须是 pyenv 安装的，才能自动链接 Homebrew 的 tcl-tk。

---

详细操作步骤

A. 安装 pyenv 并用 pyenv 安装 Python 3.12.10

1. 安装 pyenv（如未装）

brew install pyenv

2. 配置环境变量（用于 tcl-tk，临时在终端执行，长期可加到 ~/.zshrc）

export PATH="/opt/homebrew/opt/tcl-tk/bin:$PATH"
export LDFLAGS="-L/opt/homebrew/opt/tcl-tk/lib"
export CPPFLAGS="-I/opt/homebrew/opt/tcl-tk/include"
export PKG_CONFIG_PATH="/opt/homebrew/opt/tcl-tk/lib/pkgconfig"
export PYTHON_CONFIGURE_OPTS="--with-tcltk-includes='-I/opt/homebrew/opt/tcl-tk/include' --with-tcltk-libs='-L/opt/homebrew/opt/tcl-tk/lib -ltcl9.0 -ltk9.0'"

3. 用 pyenv 安装 Python 3.12.10

pyenv install 3.12.10
pyenv global 3.12.10

---

B. 用 pyenv 的 Python 新建 venv 并安装依赖

which python  # 确认路径应该是 ~/.pyenv/shims/python
python --version  # 应该是 3.12.10

用 uv pip install 或 pip install -e ".[dev]" 安装项目依赖。

---

C. 测试 tkinter 是否可用

python -c "import tkinter; print(tkinter.TkVersion)"

输出版本号说明已 OK。

---

D. 运行你的 Genesis 项目

python examples/smoke.py

此时应该不会再出现 _tkinter 的 ModuleNotFoundError。

---

重要提醒

只要你看到 /opt/homebrew/Cellar/python@3.12 路径，就是 Homebrew 的 Python，没 tkinter！

你要看到 ~/.pyenv/versions/3.12.10/bin/python 这种路径，才是 pyenv 的 Python。

---

快速排查

每次激活 venv 后，输入：

which python

• 结果应该是 ~/.pyenv/.../venv/bin/python
• 如果是 /opt/homebrew/...，说明你还在用 Homebrew Python

---

如还有卡住，请贴：

• 你激活 venv 后 which python 的输出
• python -c "import tkinter; print(tkinter.TkVersion)" 的输出

我可以帮你进一步定位！