PythonのGUIツール作成で「_tkinterモジュールが見つからない」エラーが発生した場合の対処方法

PythonでGUIアプリケーションを作成する際、_tkinterモジュールが見つからないというエラーに遭遇することがあります。特に、Homebrew経由でPythonをインストールしたMac環境でよく見られる問題です。この記事では、その原因と解決方法について詳しく解説します。

1. 必要なパッケージをインストール

まず、以下のパッケージをインストールします。
GUIを利用したアプリケーションで、CSV出力や組み合わせ生成を行うケースを想定しています。

pip install allpairspy pandas

test.pyというファイル名でコードがすでにある状態で、GUI起動用のスクリプトを実行します。

python test.py

ここで問題がなければ正常にGUIが起動するはずですが、次のようなエラーが出ることがあります。

ModuleNotFoundError: No module named '_tkinter'

このような場合には、以下の手順を試してみてください。

_tkinterモジュールが見つからない原因は、インストールされているPythonにtkinterが含まれていないことです。Mac環境ではHomebrew経由でインストールされたPythonにtkinterが含まれていないことが多く、この場合、別途インストールが必要です。

まず、python-tkをHomebrew経由でインストールします。

brew install python-tk@3.13

インストール後、以下のコマンドでtkinterが動作するか確認します。

python3 -m tkinter

tkinterはtkというGUIツールキットに依存しています。次のコマンドでtk自体もインストールしておきましょう。

brew install tcl-tk

tkのインストール先をPythonが正しく認識できるよう、環境変数を設定します。 ~/.zshrc を開いて以下を追加します。

export LDFLAGS="-L/opt/homebrew/opt/tcl-tk/lib"
export CPPFLAGS="-I/opt/homebrew/opt/tcl-tk/include"
export PATH="/opt/homebrew/opt/tcl-tk/bin:$PATH"

設定を反映するには、次のコマンドを実行します。

source ~/.zshrc

その後、再度python3 -m tkinterを試してください。

もしpyenvなどを使って異なるPythonバージョンを使用している場合、システムのPythonを使用することで解決することがあります。次のコマンドでシステムのPythonを使用するように変更できます。

pyenv global system

その後、再度python3 -m tkinterを試してください。

上記を試しても問題が解消しない場合は、Homebrew経由でインストールしたPythonをアンインストールし、再インストールしてみましょう。

brew uninstall python@3.13
brew install python@3.13

その後、再度python3 -m tkinterを試してください。

GUI開発を行う際には、tkinterが動作する環境をきちんと整えておくことが大切です。

リンク