CustomTkinter 快速上手指南：从零到第一个现代 Tkinter 应用

CustomTkinter 快速上手指南：从零到第一个现代 Tkinter 应用

【免费下载链接】CustomTkinterA modern and customizable python UI-library based on Tkinter项目地址: https://gitcode.com/gh_mirrors/cu/CustomTkinter

CustomTkinter 是基于 Tkinter 构建的现代化 Python UI 库，把桌面应用老气的默认外观换成圆角、亮暗主题和高 DPI 友好的控件。它的使用方式与标准 Tkinter 几乎一致，几分钟就能跑起第一个窗口。

环境准备：安装前确认什么

• Python ≥ 3.7：项目要求 Python 3.7 及以上，推荐 3.9+
• pip：用于安装本库及其依赖（如 darkdetect），通常随 Python 自带
• Tkinter 模块：Windows / macOS 的官方安装包已内置；Linux 可能需要单独执行sudo apt install python3-tk
• Pillow（可选）：只在需要显示图片控件时才需要

快速自检环境是否就绪：

python --version

版本号在 3.7 及以上即可继续安装。

📦 快速安装

pip install customtkinter

安装后跑一行验证，能打印出版本号（6.x）即代表成功：python -c "import customtkinter; print(customtkinter.__version__)"

已有旧版本的用户，执行pip install customtkinter --upgrade升级到最新版即可。

🔍 核心能力一览

• 全套现代控件：CTkButton、CTkSlider、CTkOptionMenu、CTkTabview、CTkScrollableFrame等覆盖常见桌面场景，布局接口与标准 Tkinter 完全一致（pack/grid/place）
• 亮 / 暗主题切换：set_appearance_mode("System")一行代码让整窗跟随系统亮暗外观，也可强制 "Light" 或 "Dark"
• 内置配色主题：set_default_color_theme提供 "blue" / "green" / "dark-blue" 三套配色，切换后所有控件颜色统一更新
• 高 DPI 缩放：在 Windows 和 macOS 高分辨率屏幕上控件自动缩放，文字与边框保持清晰
• 可与原生 Tkinter 混用：CTk 窗口里既能放标准 Tkinter 控件，也能放 CustomTkinter 控件

🚀 实战演示

第一个示例是最小可运行窗口：一个主窗口加一个按钮，共 10 行代码：

import customtkinter customtkinter.set_appearance_mode("dark") # 外观模式：System / Light / Dark customtkinter.set_default_color_theme("blue") # 内置配色主题：blue / green / dark-blue app = customtkinter.CTk() # 创建主窗口 app.geometry("400x240") # CTkButton 与 tkinter 的 Button 用法一致 button = customtkinter.CTkButton(master=app, text="CTkButton", command=lambda: print("clicked")) button.place(relx=0.5, rely=0.5) app.mainloop()

CustomTkinter 单按钮示例在 macOS 暗色模式下的运行效果

进阶小例子演示CTkScrollableFrame：把若干CTkLabel放进滚动框架，内容超出时自动出现滚动条，适合做长列表：

import customtkinter app = customtkinter.CTk() app.geometry("400x300") # 可滚动框架：内容超出高度时自动带滚动条 frame = customtkinter.CTkScrollableFrame(app, width=350, height=250) frame.pack(pady=20) for i in range(20): customtkinter.CTkLabel(frame, text=f"Item {i + 1}").pack(pady=5) app.mainloop()

CustomTkinter 可滚动框架示例，内含多个控件并可上下滚动

更完整的控件组合与主题切换可以查看 完整示例代码。

⚙️ 配置与自定义

最常用的三个全局配置项：

• appearance_mode（set_appearance_mode）：可选 "System" / "Light" / "Dark"，控制整个界面是否跟随系统亮暗
• color_theme（set_default_color_theme）：可选 "blue" / "green" / "dark-blue"，统一所有控件的配色方案
• widget_scaling（set_widget_scaling）：可选1.1这类浮点数，手动微调整体 UI 缩放比例

customtkinter.set_appearance_mode("Light") customtkinter.set_default_color_theme("green") customtkinter.set_widget_scaling(1.1)

❓ 常见疑问

Q：Linux 下运行示例报No module named tkinter怎么办？系统缺少 Tkinter 模块，执行sudo apt install python3-tk安装（Debian/Ubuntu 系），然后重新运行即可。

Q：CTk 控件能和标准 tkinter 控件混用吗？可以。CTk 窗口与控件和标准 Tkinter 一样支持pack/grid/place，在同一界面里自由混放标准控件没问题。

Q：按钮上想显示图片，需要什么依赖？先pip install pillow，再用CTkImage包装 PIL 的 Image 对象，传给CTkButton的image参数即可。

CustomTkinter 把 Python 桌面应用的视觉门槛降到了最低：装好、写出第一个窗口，就拥有了现代感 UI。现在就可以打开examples/simple_example.py跑一遍控件全家福。

【免费下载链接】CustomTkinterA modern and customizable python UI-library based on Tkinter项目地址: https://gitcode.com/gh_mirrors/cu/CustomTkinter