Unable to install tkinter with pyenv Pythons on MacOS

TL;DR set the env. vars. mentioned in tcl-tk's caveats and this GitHub comment when installing new Pythons via pyenv to get tkinter.

First, ensure you have the latest tcl-tk via homebrew and then pay attention to its caveats:

※ brew install tcl-tk※ brew info tcl-tktcl-tk: stable 8.6.10 (bottled) [keg-only]...==> Caveatstcl-tk is keg-only, which means it was not symlinked into /usr/local,because tk installs some X11 headers and macOS provides an (older) Tcl/Tk.If you need to have tcl-tk first in your PATH run:  echo 'export PATH="/usr/local/opt/tcl-tk/bin:$PATH"' >> ~/.zshrcFor compilers to find tcl-tk you may need to set:  export LDFLAGS="-L/usr/local/opt/tcl-tk/lib"  export CPPFLAGS="-I/usr/local/opt/tcl-tk/include"For pkg-config to find tcl-tk you may need to set:  export PKG_CONFIG_PATH="/usr/local/opt/tcl-tk/lib/pkgconfig"...

You'll also need to know about pyenv's PYTHON_CONFIGURE_OPTS, --with-tcltk-includes, and --with-tcltk-libs, e.g. from this comment.

Next, reinstall Python with the environment variables active:

※ pyenv uninstall 3.8.1※ env \  PATH="$(brew --prefix tcl-tk)/bin:$PATH" \  LDFLAGS="-L$(brew --prefix tcl-tk)/lib" \  CPPFLAGS="-I$(brew --prefix tcl-tk)/include" \  PKG_CONFIG_PATH="$(brew --prefix tcl-tk)/lib/pkgconfig" \  CFLAGS="-I$(brew --prefix tcl-tk)/include" \  PYTHON_CONFIGURE_OPTS="--with-tcltk-includes='-I$(brew --prefix tcl-tk)/include' --with-tcltk-libs='-L$(brew --prefix tcl-tk)/lib -ltcl8.6 -ltk8.6'" \  pyenv install 3.8.1

It should work now:

※ pyenv global 3.8.1※ pythonPython 3.8.1 (default, Feb 29 2020, 11:56:10)[Clang 11.0.0 (clang-1100.0.33.17)] on darwinType "help", "copyright", "credits" or "license" for more information.>>> import tkinter>>> tkinter.TclVersion, tkinter.TkVersion(8.6, 8.6)>>> tkinter._test()# You should get a GUI

If you get the following error, you might be missing the PYTHON_CONFIGURE_OPTS env. var. above.

DEPRECATION WARNING: The system version of Tk is deprecated and may be removed in a future release. Please don't rely on it. Set TK_SILENCE_DEPRECATION=1 to suppress this warning.Traceback (most recent call last):  File "<stdin>", line 1, in <module>  File "/Users/factor/.pyenv/versions/3.8.1/lib/python3.8/tkinter/__init__.py", line 4552, in _test    root = Tk()  File "/Users/factor/.pyenv/versions/3.8.1/lib/python3.8/tkinter/__init__.py", line 2263, in __init__    self._loadtk()  File "/Users/factor/.pyenv/versions/3.8.1/lib/python3.8/tkinter/__init__.py", line 2279, in _loadtk    raise RuntimeError("tk.h version (%s) doesn't match libtk.a version (%s)"RuntimeError: tk.h version (8.6) doesn't match libtk.a version (8.5)

Here is step by step guide to make tkinter (and IDLE) work if you use pyenv for Python environments management on macOS:

1. install tcl-tk with Homebrew. In shell run brew install tcl-tk
2. in shell run echo 'export PATH="/usr/local/opt/tcl-tk/bin:$PATH"' >> ~/.zshrc
3. reload shell by quitting Terminal app or run source ~/.zshrc
4. after reloaded check that tck-tk is in $PATH. Run echo $PATH | grep --color=auto tcl-tk. As the result you should see your $PATH contents with tcl-tk highlighted
5. now we run three commands from Homebrew's output from step #1
   1. in shell run export LDFLAGS="-L/usr/local/opt/tcl-tk/lib"
   2. in shell run export CPPFLAGS="-I/usr/local/opt/tcl-tk/include"
   3. in shell run export PKG_CONFIG_PATH="/usr/local/opt/tcl-tk/lib/pkgconfig"
6. if you have your Python version already installed with pyenv then uninstall it with pyenv uninstall <your python version>. E.g. pyenv uninstall 3.8.2
7. set environment variable that will be used by python-build. In shell run PYTHON_CONFIGURE_OPTS="--with-tcltk-includes='-I/usr/local/opt/tcl-tk/include' --with-tcltk-libs='-L/usr/local/opt/tcl-tk/lib -ltcl8.6 -ltk8.6'"Note: in future use tck-tk version that actually installed with Homebrew. At the moment of posting 8.6 was the actual
8. finally install Python with pyenv with pyenv install <version>. E.g. pyenv install 3.8.2

Test

1. in shell run pyenv global <verion that you've just installed>
2. now check IDLE. In shell run idle. You should see IDLE window without any warnings and "text printed in red".

3. now check tkinter. In shell run python -m tkinter -c "tkinter._test()". You should see test window like on the image:

That's it!

My environment:

check this is something went wrong executing steps above:

1. macOS Catalina
2. zsh (included in macOS Catalina) = "shell" above
3. Homebrew (installed with instructions from Homebrew official website)
4. pyenv (installed with Homebrew and PATH updated according to pyenv official readme from GitHub)
5. Python 3.8.x - 3.9.x (installed with pyenv install <version> command)

For MacOS Big Sur (11.2.3), Carl G's answer didn't work for me because I got a zlib error. Building off of this answer and this blog post, I found success with

brew install bzip2export LDFLAGS="-L $(xcrun --show-sdk-path)/usr/lib -L brew --prefix bzip2/lib"export CFLAGS="-L $(xcrun --show-sdk-path)/usr/include -L brew --prefix bzip2/include"export PYTHON_CONFIGURE_OPTS="--with-tcltk-includes='-I/usr/local/opt/tcl-tk/include' --with-tcltk-libs='-L/usr/local/opt/tcl-tk/lib -ltcl8.6 -ltk8.6' --enable-framework"pyenv install 3.8.6