The “ModuleNotFoundError: No module named ‘_tkinter'” error on macOS occurs when Tkinter is missing from the Python installation. Tkinter is the default GUI toolkit for Python, but macOS versions of Python may not include it by default. This tutorial will guide you through fixing this issue.

Possible reasons for this error:

  • Python was installed without Tkinter.
  • Using Homebrew Python, which may not include Tkinter.
  • Missing Tcl/Tk libraries.
  • Virtual environment issues.

Fix “ModuleNotFoundError: No module named ‘_tkinter'” on macOS

Step 1: Check If Tkinter Is Installed

Run the following command in the terminal:

python3 -m tkinter

If Tkinter is installed, a small GUI window should appear. If not, proceed to the next step.

Step 2: Install Tcl/Tk on macOS

Install Tcl/Tk using Homebrew:

brew install tcl-tk

Check the installation path:

brew info tcl-tk

Step 3: Link Tcl/Tk to Python

Add the following environment variables to your shell profile:

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"

Apply the changes:

source ~/.zshrc

Step 4: Reinstall Python with Tkinter Support

If using Homebrew Python, reinstall Tkinter support:

brew reinstall python-tk

If using pyenv, install Python with Tkinter support:

PYTHON_CONFIGURE_OPTS="--with-tcltk" pyenv install 3.x.x

Step 5: Verify Tkinter Installation

Test if Tkinter is working:

python3 -c "import tkinter; tkinter._test()"

If a GUI window appears, Tkinter is installed correctly.

Alternative: Use System Python

If using Homebrew Python, try running:

/usr/bin/python3 -m tkinter

If this works, you may need to switch to the system Python.