Python

How to Fix the “_tkinter module not found” Error When Creating a Python GUI Tool

 

When creating a GUI application with Python, you may encounter an error stating that the _tkinter module cannot be found. This is a common issue, especially in Mac environments where Python is installed via Homebrew. In this article, we’ll explain the cause of the error and how to resolve it in detail.

Contents
  1. 1. Install Required Packages
  2. 2.Install tkinter
  3. 3. Use System Python
  4. 4. Uninstall and Reinstall Homebrew Python
  5. Summary

1. Install Required Packages

First, install the following packages.
Assuming you are building a GUI application that performs CSV export and combination generation:

pip install allpairspy pandas

 

  • allpairspy: A library for automatic generation of pairwise test cases

  • pandas: A library for processing data such as CSV files

With a file named test.py already created, run the script to launch the GUI:

python test.py

 

If there are no issues, the GUI should launch normally. However, you may encounter the following error:

ModuleNotFoundError: No module named '_tkinter'

 

In such cases, try the following steps.

 

2.Install tkinter

The reason for the _tkinter module not being found is that the installed Python does not include tkinter. On Mac, Python installed via Homebrew often does not come with tkinter, so you will need to install it separately.

 

2-1. Install python-tk

First, install python-tk via Homebrew:

brew install python-tk@3.13

After installation, check if tkinter works with the following command:

python3 -m tkinter

 

2-2. Install the tk Library

tkinter depends on a GUI toolkit called tk. Install tk itself using the following command:

brew install tcl-tk

 

2-3.Set Environment Variables

To ensure Python correctly recognizes the installation path of tk, set the environment variables.
Open ~/.zshrc and add the following:

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"

 

To apply the settings, run the following command:

source ~/.zshrc

 

Then, try running python3 -m tkinter again.

 

3. Use System Python

If you are using a different version of Python via pyenv or similar, switching to the system’s Python may resolve the issue.
Use the following command to switch:

pyenv global system

 

Then, try running python3 -m tkinter again.

 

4. Uninstall and Reinstall Homebrew Python

If the above methods still don’t resolve the issue, try uninstalling and reinstalling the Python installed via Homebrew:

brew uninstall python@3.13
brew install python@3.13

 

Then, try running python3 -m tkinter again.

 

Summary

  • The _tkinter module error is caused by the absence of tkinter in the Python installation.

  • Python installed via Homebrew may not include tkinter by default.

  • Installing tcl-tk and setting environment variables is essential.

  • If using pyenv, trying the system Python may help.

When developing GUIs, it is important to ensure that the environment is properly set up to support tkinter.

RELATED POST