Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/TomSchimansky/CustomTkinter/llms.txt

Use this file to discover all available pages before exploring further.

​
Installing CustomTkinter

CustomTkinter is available on PyPI and can be installed using pip. The library works on Windows, macOS, and Linux.

​
Requirements

CustomTkinter requires:
  • Python 3.7 or higher
  • Tkinter (usually included with Python)
On macOS, Python 3.10 or higher (or Anaconda Python) is recommended for proper dark window headers. This requires Tcl/Tk >= 8.6.9.

​
Install with pip

Install CustomTkinter using pip: 
pip3 install customtkinter

​
Updating CustomTkinter

CustomTkinter is under active development with frequent updates and improvements. It’s recommended to update regularly: 
pip3 install customtkinter --upgrade
Update CustomTkinter as often as possible to get the latest features, bug fixes, and improvements. New versions are released regularly.

​
Verify Installation

After installation, verify that CustomTkinter is installed correctly by checking the version: 
import customtkinter
print(customtkinter.__version__)
The current stable version is 5.2.2.

​
Platform-Specific Notes

​
Windows

On Windows, CustomTkinter works out of the box with Python installations from python.org. The library automatically handles:
  • HighDPI scaling
  • System appearance mode detection
  • Dark/light theme switching

​
macOS

For the best experience on macOS:
1

Use Python 3.10+

Install Python 3.10 or higher to get proper dark window headers and title bars.
2

Or Use Anaconda

Alternatively, use Anaconda Python which includes the required Tcl/Tk version (>= 8.6.9).
With older Python versions on macOS, CustomTkinter will still work, but window title bars may not adapt to dark mode.

​
Linux

On Linux, ensure Tkinter is installed: 
# Ubuntu/Debian
sudo apt-get install python3-tk

# Fedora
sudo dnf install python3-tkinter

# Arch Linux
sudo pacman -S tk

​
Troubleshooting

​
Tkinter Not Found

If you get an error that Tkinter is not installed:
  1. Windows/macOS: Tkinter should be included with Python. Reinstall Python from python.org.
  2. Linux: Install the python3-tk package (see Linux section above).

​
Import Error

If you get an import error after installation: 
ImportError: No module named 'customtkinter'
Make sure you’re using the correct Python environment: 
# Check which Python you're using
python --version
python3 --version

# Install to the correct Python version
python3 -m pip install customtkinter

​
Next Steps

Now that CustomTkinter is installed, you’re ready to build your first application:

Quick Start Guide

Create your first CustomTkinter window with a button in just a few lines of code

Build docs developers (and LLMs) love

Get started for freeTalk to us