CustomTkinter

5.2.2 · active · verified Sun Apr 12

CustomTkinter is a Python UI library based on Tkinter, designed to create modern-looking and fully customizable graphical user interfaces. It provides a consistent and aesthetically pleasing experience across Windows, macOS, and Linux platforms, enhancing standard Tkinter widgets with advanced styling. The library is actively developed, with its current version being 5.2.2.

Warnings

breaking Version 5.0.0 introduced significant breaking changes, including: `text_font` attributes renamed to `font`, transparent color values changing from `None` to the string `'transparent'`, and a complete overhaul of custom theme file formats.
Fix: Review the official migration guide for v5.0.0. Update font attribute names from `text_font` to `font`. Change `fg_color=None` to `fg_color='transparent'` for transparent elements. Custom theme files will need to be re-structured to the new JSON format.
gotcha ModuleNotFoundError for 'customtkinter' often occurs due to incorrect Python interpreter selection in IDEs (like VS Code) when using virtual environments, or due to incorrect capitalization in import statements (e.g., `from CustomTkinter import CTk`).
Fix: Ensure your IDE is configured to use the correct Python interpreter associated with your virtual environment where CustomTkinter is installed. Always use `import customtkinter` (lowercase 'c') and refer to classes with the `customtkinter.` prefix (e.g., `customtkinter.CTk`).
gotcha Displaying images within CustomTkinter widgets (e.g., `CTkButton` or `CTkLabel`) requires the Pillow library to be installed separately, as it is an optional dependency.
Fix: Install Pillow using `pip install Pillow` if you plan to use images in your CustomTkinter application.
gotcha CustomTkinter, being built on Tkinter, implicitly relies on the Tcl/Tk GUI toolkit. While typically bundled with Python, some environments (especially minimal Linux installations or specific Python builds) may require manual installation of Tcl/Tk system packages.
Fix: If encountering issues related to the underlying GUI framework, ensure Tcl/Tk development packages are installed on your operating system (e.g., `sudo apt-get install python3-tk` on Debian/Ubuntu, or `brew install tcl-tk` on macOS for Homebrew Python).

Install

pip install customtkinter Install latest stable version

Imports

customtkinter
```
import customtkinter
```
Module name is lowercase: `customtkinter`. Classes are typically accessed as `customtkinter.CTk`, `customtkinter.CTkButton`, etc. or after aliasing: `import customtkinter as ctk`.
CTk
```
import customtkinter as ctk
app = ctk.CTk()
```
While `from customtkinter import *` works, it's generally discouraged in production code. Explicitly importing `customtkinter` and using the prefix `customtkinter.CTk` or an alias `ctk.CTk` is preferred for clarity and avoiding name clashes.

Quickstart

This quickstart initializes a basic CustomTkinter window, sets the appearance mode and color theme, and adds a centered button that prints a message when clicked.

import customtkinter

customtkinter.set_appearance_mode("System")  # Modes: "System" (default), "Dark", "Light"
customtkinter.set_default_color_theme("blue")  # Themes: "blue" (default), "dark-blue", "green"

app = customtkinter.CTk() # create CTk window
app.geometry("400x240")
app.title("My CTk App")

def button_function():
    print("Button pressed!")

# Create a button
button = customtkinter.CTkButton(master=app, text="Click Me", command=button_function)
button.place(relx=0.5, rely=0.5, anchor=customtkinter.CENTER)

app.mainloop()

view raw JSON →