Skip to main content

​
Quick Start Guide

This guide will help you create your first CustomTkinter application with a working window and interactive button.

​
Basic Window with Button

Let’s create a simple application with a window and a button: 
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 like you do with the Tk window
app.geometry("400x240")

def button_function():
    print("button pressed")

# Use CTkButton instead of tkinter Button
button = customtkinter.CTkButton(master=app, text="CTkButton", command=button_function)
button.place(relx=0.5, rely=0.5, anchor=customtkinter.CENTER)

app.mainloop()
This example is from the official CustomTkinter README and demonstrates the simplest possible CustomTkinter application.

​
Understanding the Code

1

Import CustomTkinter

import customtkinter
Import the CustomTkinter library. No need to import tkinter separately.
2

Configure Appearance

customtkinter.set_appearance_mode("System")  # Modes: "System", "Dark", "Light"
customtkinter.set_default_color_theme("blue")  # Themes: "blue", "dark-blue", "green"
Set the appearance mode and color theme. System mode automatically adapts to your OS theme.
3

Create Main Window

app = customtkinter.CTk()
app.geometry("400x240")
Create the main application window using CTk() instead of tkinter.Tk().
4

Add Widgets

button = customtkinter.CTkButton(master=app, text="CTkButton", command=button_function)
button.place(relx=0.5, rely=0.5, anchor=customtkinter.CENTER)
Create and place widgets just like in Tkinter, using the CTk prefix.
5

Start Event Loop

app.mainloop()
Start the application event loop to display the window and handle events.

​
Multiple Widgets Example

Here’s a more comprehensive example with multiple widgets in a frame: 
import customtkinter

customtkinter.set_appearance_mode("dark")
customtkinter.set_default_color_theme("blue")

app = customtkinter.CTk()
app.geometry("400x300")
app.title("CustomTkinter Example")

def button_callback():
    print("Button clicked:", entry_1.get())

def slider_callback(value):
    progressbar_1.set(value)

# Create a frame to hold widgets
frame_1 = customtkinter.CTkFrame(master=app)
frame_1.pack(pady=20, padx=60, fill="both", expand=True)

# Add various widgets
label_1 = customtkinter.CTkLabel(master=frame_1, text="CustomTkinter App")
label_1.pack(pady=10, padx=10)

entry_1 = customtkinter.CTkEntry(master=frame_1, placeholder_text="Enter text here")
entry_1.pack(pady=10, padx=10)

button_1 = customtkinter.CTkButton(master=frame_1, text="Click Me", command=button_callback)
button_1.pack(pady=10, padx=10)

progressbar_1 = customtkinter.CTkProgressBar(master=frame_1)
progressbar_1.pack(pady=10, padx=10)
progressbar_1.set(0.5)

slider_1 = customtkinter.CTkSlider(master=frame_1, command=slider_callback, from_=0, to=1)
slider_1.pack(pady=10, padx=10)
slider_1.set(0.5)

app.mainloop()
This example is adapted from the official simple_example.py in the CustomTkinter repository. It demonstrates how to use frames, labels, entries, buttons, progress bars, and sliders together.

​
Appearance Modes

CustomTkinter supports three appearance modes: 
customtkinter.set_appearance_mode("System")
# Automatically adapts to your OS dark/light mode

​
Color Themes

Choose from built-in color themes or create your own: 
customtkinter.set_default_color_theme("blue")

​
Layout Management

CustomTkinter supports all standard Tkinter layout managers:

​
Pack

button.pack(pady=10, padx=10)

​
Grid

button.grid(row=0, column=0, padx=20, pady=10)

​
Place

button.place(relx=0.5, rely=0.5, anchor=customtkinter.CENTER)

​
Common Widget Parameters

All CustomTkinter widgets support common parameters:
  • master - Parent widget or window
  • width - Widget width in pixels
  • height - Widget height in pixels
  • corner_radius - Corner radius for rounded edges
  • fg_color - Foreground/background color
  • text_color - Text color
  • font - Font (string or CTkFont object)

​
Next Steps

Now that you’ve created your first CustomTkinter application, explore more features:

Widget Gallery

Explore all available widgets and their properties

Scaling & DPI

Learn about HighDPI scaling and widget/window scaling

Custom Themes

Create custom color themes for your applications

Complex Examples

Study advanced examples with multiple widgets and layouts
All CustomTkinter widgets can be mixed with standard Tkinter widgets in the same application. You can gradually migrate existing Tkinter apps to CustomTkinter.

Build docs developers (and LLMs) love

Get started for freeTalk to us