tkinter documentation: missing information about tkinter availability and bundling details

[zahlman]

Documentation

Aside from the actual use of Tkinter, the documentation is quite light on details about installation. Although the basic architecture is described, the documentation seems to assume that Tkinter will be available in every Python installation:

The tkinter package (“Tk interface”) is the standard Python interface to the Tcl/Tk GUI toolkit. Both Tk and tkinter are available on most Unix platforms, including macOS, as well as on Windows systems.

Running python -m tkinter from the command line should open a window demonstrating a simple Tk interface, letting you know that tkinter is properly installed on your system, and also showing what version of Tcl/Tk is installed, so you can read the Tcl/Tk documentation specific to that version.

Tkinter supports a range of Tcl/Tk versions, built either with or without thread support. The official Python binary release bundles Tcl/Tk 8.6 threaded. See the source code for the _tkinter module for more information about supported versions.

However, this is clearly not the case - many Python installations are compiled without Tkinter support. For example, many Linux distributions do not include it in the system Python, and the Windows installer offers an option to omit it. This creates a surprisingly complex trap for many users - especially beginners following tutorials that assume that turtle will be available and work properly, but also power users.

What I have been able to figure out so far:

1. Neither tkinter nor turtle (nor IDLE, though this is more obvious) can be installed via PyPI. Worse: there are many packages that look like they might add Tkinter support to an installation that lacks it, but don't - instead, they're various wrappers or enhancements for Tkinter functionality (including some that literally just define some constants). To say nothing of countless demo Tkinter projects. Of course, name squatting is endemic to PyPI, but it's especially problematic here.

2. Even worse: there is a package on PyPI with the exact name turtle - but it does something completely different (HTTP throttling) and is extremely outdated (last modified 2009, version 0.0.2, code is 2.x only). There's also a tk package that seems to be something related to Tensorflow. There are many anecdotal reports (e.g. on Stack Overflow and other Stack Exchange sites) of people mistakenly installing (or attempting to install) these packages.

3. Unlike pip etc., virtual environments created from a base installation that lacks Tkinter support will also lack Tkinter support; and it can't be bootstrapped or otherwise overridden. If Tkinter support is later added to the base installation, this will normally not be reflected in the virtual environment.

4. The expected way to add Tkinter support to a Windows distribution is to use Windows' "repair installation" functionality to re-run the installer. However, this obviously only works for Pythons that were created from the official binary installer. Further, adding Tcl/Tk support entails adding IDLE, which some users might not care for.

5. The expected way to add Tkinter support to a Linux distribution, at least on Ubuntu (and variants such as Mint), is to install the python3-tk package. However, this will only modify the system Python, and can't update virtual environments, nor other versions of Python (including ones compiled from source).

I have no idea about Mac, although I assume it is similar to Linux in this regard. At any rate, I don't see any supported way to add Tkinter support directly to a virtual environment. Even if you only have one version of Python on the system, it seems you are expected to update that root installation and then re-create any virtual environments that need the support. This is also obnoxious for Mac and Linux users who, like myself, would like to experiment with Tkinter but do not want to modify the system Python as a matter of principle.

I have also noticed that some installations that lack Tkinter support will still include turtle.py in the standard library, and others will not. For example, on my system I see

$ python -m turtle
Traceback (most recent call last):
  File "/usr/lib/python3.8/runpy.py", line 194, in _run_module_as_main
    return _run_code(code, main_globals, None,
  File "/usr/lib/python3.8/runpy.py", line 87, in _run_code
    exec(code, run_globals)
  File "/usr/lib/python3.8/turtle.py", line 107, in <module>
    import tkinter as TK
ModuleNotFoundError: No module named 'tkinter'

whereas many others report (e.g.) that the import of turtle itself will directly fail.

I am requesting that the documentation should clearly explain:

1. The fact that tkinter won't always be available

2. A recommended, standard way to add Tkinter support to installations - including virtual environments - that lack it, per installation (which entails ensuring that there is such a way; failing that, at least acknowledge and explain the limitation)

3. Exactly how a given Python installation locates the Tcl interpreter and Tk package that it will use, including any relevant environment variables

4. Exactly how bundled versions of Tcl/Tk (for 3.10 and up, where it's bundled) are managed: will the installer update an existing system Tcl/Tk installation? Manage a completely isolated copy of those libraries? Something else? (For example: if I install 3.10 and then 3.9 on a new Windows machine, will the 3.9 installation make use of the Tcl/Tk that was bundled with 3.10?)

Aside from that, there are many popular libraries (e.g. matplotlib) that do not strictly require Tkinter support, but tend to assume its presence by default. It would be nice for the official doc to include some information or references for troubleshooting these issues.

[terryjreedy]

The pypi stuff is a different issue. Perhap it might belong under packaging.

1. yes.
2. OS-specific stuff belongs in the Using document, in the OS-specific sections.
3. I don't know if this is OS-specific or not, but think it must be.
4. The Windows installers install tcl/tk as part of the 3.y.z installation. Each installation has its own copy of tcl/tk and _tkinter tested against the tk version installed. The same should be true on MacOS unless care is taken to install only one copy of any particular tcl/tk even if used for multiple releases. On Linux, tcl/tk is installed managed by the OS. (I know nothing about venvs.

I am willing to review PRs and might make one myself.

EDIT: point 4 clarified.

[zahlman]

I should mention: my underlying purpose here is to prepare an authoritative guide about such installation on Stack Overflow. I initially didn't notice the Discourse link; now I have and I'll ask there more directly for the information I need - but since I'd thought first to look at the documentation, I saw an opportunity to propose filling in some information there, too.

The pypi stuff is a different issue. Perhap it might belong under packaging.

I understand that the Python dev team doesn't control what ends up on PyPI - my commentary there is mainly to show the severity of the problem (and also just collecting my thoughts).

OS-specific stuff belongs in the Using document, in the OS-specific sections.

I had hoped that a platform-agnostic way might exist (e.g., something analogous to ensurepip) but it seems like that would need to be a separate feature request.

The Windows and macOS install tcl/tk as part of the 3.y.z installation. On Linux, tcl/tk is installed managed by the OS. (I know nothing about venvs.

I'm not really sure what to make of "install" in this context. What I am trying to figure out generally is: a) could multiple tcl/tks end up on the system? b) if so, which one will be used by which _tkinter module?

[terryjreedy]

See edited point 4 above for clarification of 'install'.