Registry / web-framework / customtkinter

customtkinter

library6.0.0pypypi✓ verified 24d ago

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.

web-framework

pip install customtkinter

package ↗homepage ↗

INSTALL

IMPORT

SIG · CUSTOMTKINTER

customtkinter

web-frameworkpythonv6.0.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

customtkinter

✓ import customtkinter

✗ from CustomTkinter import CTk

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()

✗ from customtkinter import * app = 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.

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()

Debug

Known issues

breakingVersion 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.

affects: 5.0.0+

gotchaModuleNotFoundError 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`).

affects: All versions

gotchaDisplaying 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.

affects: All versions

gotchaCustomTkinter, 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).

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'customtkinter'

The `customtkinter` library is either not installed in the Python environment being used, or the Python interpreter configured in the IDE or system path does not point to the environment where it is installed.

fix

Ensure `customtkinter` is installed using `pip install customtkinter`. If using a virtual environment or IDE (like VS Code or PyCharm), verify that the correct Python interpreter associated with the installed package is selected.

AttributeError: module 'customtkinter' has no attribute 'CTk'

This error most commonly occurs due to incorrect capitalization (e.g., using `CTK` instead of `CTk`) or if the Python file itself is named `customtkinter.py`, leading to a circular import where Python tries to import from the local file instead of the actual library.

fix

Correct the capitalization to `customtkinter.CTk()` and ensure your Python script is not named `customtkinter.py` or any name that conflicts with the library's module name.

AttributeError: module 'customtkinter' has no attribute 'set_appearance_mode'

Similar to `AttributeError` for `CTk`, this is often caused by a capitalization error (`set_appearance_mode` vs `set_Appearance_Mode`) or a circular import if a local file is named `customtkinter.py`.

fix

Verify the method name is correctly spelled and capitalized as `customtkinter.set_appearance_mode()`. Also, check that your Python script file is not named `customtkinter.py`.

customtkinter widgets not showing/appearing

Widgets might not appear if a geometry manager (like `.pack()`, `.grid()`, or `.place()`) is not called on them, if they are placed in overlapping rows/columns, or if there are issues with the Python or CustomTkinter version, especially on Linux with scaling or older Python versions.

fix

Always call a geometry manager (e.g., `widget.pack()`, `widget.grid()`, or `widget.place()`) after creating a widget. Ensure consistent use of geometry managers within the same container. Consider updating CustomTkinter and Python to their latest stable versions, and be aware of potential display issues on Linux with desktop scaling, sometimes resolvable by using a virtual environment or switching Python versions.

AttributeError: 'int' object has no attribute '_root'

This error typically occurs when a `customtkinter.IntVar()`, `StringVar()`, `DoubleVar()`, or `BooleanVar()` is initialized without a master widget, or when an integer value is mistakenly passed as the master instead of a widget.

fix

When creating a `customtkinter` variable (e.g., `IntVar`), ensure you pass a valid master widget (like the main application window) as the first argument, or use the `value` keyword for the initial value. For example, `my_var = customtkinter.IntVar(master=app, value=0)`.

Upgrade

Version history

6.0.0latest on PyPI · released Jun 24, 2026

Audit

Dependencies

typing-extensionsrequiredInternal type hinting support.

packagingrequiredUsed for version parsing and compatibility checks.

darkdetectrequiredEnables detection of system appearance mode (light/dark).

PillowoptionalRequired for displaying images within CustomTkinter widgets, such as on CTkButton or CTkLabel.

tkrequiredCustomTkinter is built on top of Tkinter, which in turn relies on the Tcl/Tk GUI toolkit. This is typically bundled with Python but might need system-level installation on some Linux distributions or specific environments.

Agent activity

0 hits · last 30 days

No traffic data recorded yet.

Resources

packagehttps://pypi.org/project/customtkinter/ ↗

homepagehttps://customtkinter.tomschimansky.com ↗